API de consentimento
Para o servidor da sua empresa consultar o que um visitante decidiu e registrar decisões coletadas fora do banner da Trusto. Todo registro fica na mesma trilha de prova do banner, ligado à organização dona da chave.
Endereços
Use a chave do ambiente correspondente. Uma chave de teste não vale em produção, e o contrário também não.
| Ambiente | Endereço | Prefixo da chave |
|---|---|---|
| Teste | https://api.staging.gettrusto.io | trusto_sk_test_… |
| Produção | https://api.gettrusto.io | trusto_sk_live_… |
Autenticação
Toda rota exige a chave no cabeçalho Authorization, no formato Bearer.
Authorization: Bearer trusto_sk_test_…Um administrador da organização cria a chave em Configurações, aba Chaves de API, com uma ou duas permissões. As permissões não mudam depois da criação: para mudar, crie outra chave e revogue a antiga.
consent:read: consultar recibos e histórico.consent:write: registrar decisões.
A organização é sempre a da chave. Nada no corpo, na consulta ou no caminho escolhe a organização.
Toda resposta é JSON e não deve ser guardada em cache.
A chave é secreta e fica só no servidor
Guarde a chave numa variável de ambiente ou num cofre de segredos do servidor. Nunca a coloque em código que roda no navegador nem dentro de um aplicativo móvel: qualquer pessoa extrai a chave do pacote do aplicativo. A API não aceita chamadas de navegador. Se uma chave vazar, revogue na mesma aba em que ela foi criada.
Aplicativo móvel: o aplicativo envia a decisão ao servidor da sua empresa, e o servidor chama a API com a chave. Um SDK móvel que dispensa esse servidor está planejado.
Rotas
Consultar um recibo
/v1/consents/{consentId}
Permissão: consent:read
O consentId é o identificador que o banner devolve ao visitante como recibo. Maiúsculas e minúsculas são indiferentes.
Pedido
curl -H "Authorization: Bearer $TRUSTO_KEY" \
https://api.staging.gettrusto.io/v1/consents/c0ffee00-0000-4000-8000-000000000000Resposta
200
{
"consentId": "c0ffee00-0000-4000-8000-000000000000",
"domain": "acme.com.br",
"visitorId": "45b2690e-c9b2-463f-91e8-2b115f888044",
"action": "accept_all",
"categories": {
"necessary": true,
"analytics": true
},
"configVersion": 2,
"source": "widget",
"createdAt": "2026-10-17T00:00:00.000Z",
"expiresAt": "2027-10-17T00:00:00.000Z",
"erased": false
}Recibo inexistente, de outra organização ou fora do formato: 404 consent_not_found.
Histórico de um visitante
/v1/consents?visitorId={uuid}&cursor={cursor}
Permissão: consent:read
Os registros do visitante, dos mais novos para os mais antigos, 100 por página.
Pedido
curl -H "Authorization: Bearer $TRUSTO_KEY" \
"https://api.staging.gettrusto.io/v1/consents?visitorId=45b2690e-c9b2-463f-91e8-2b115f888044"Resposta
200
{
"consents": [
{
"consentId": "c0ffee00-0000-4000-8000-000000000000",
"...": "..."
}
],
"nextCursor": "WzE3NjA2NjU2MDAsMCwiYzBmZmVlMDAtLi4uIl0"
}- Para a próxima página, repita a chamada com cursor igual ao nextCursor recebido. Quando nextCursor vier null, é a última página.
- O cursor é opaco. Um cursor inválido volta à primeira página, sem erro.
- Sem visitorId ou com visitorId fora do formato UUID: 400 invalid_request.
- Visitante sem registros: 200 com a lista vazia.
Registrar uma decisão
/v1/consents
Permissão: consent:write
Para decisões coletadas fora do banner da Trusto (banner próprio, checkout, aplicativo com backend), sempre sobre um banner publicado num domínio da organização.
Pedido
curl -X POST https://api.staging.gettrusto.io/v1/consents \
-H "Authorization: Bearer $TRUSTO_KEY" \
-H "Content-Type: application/json" \
-d '{"domain":"acme.com.br","visitorId":"45b2690e-c9b2-463f-91e8-2b115f888044","action":"partial","categories":{"necessary":true,"analytics":true,"marketing":false},"configVersion":2}'Resposta
201
{
"consentId": "9b1c2d3e-0000-4000-8000-000000000000",
"expiresAt": "2027-10-17T18:00:00.000Z"
}| Campo | Regra |
|---|---|
| domain | Nome do domínio como cadastrado, sem https://, porta ou caminho. Precisa ter banner publicado nesta organização. |
| visitorId | UUID que identifica o visitante no seu sistema. É por ele que o histórico e os pedidos de titular encontram o registro. |
| action | Um de: accept_all, reject_all, partial, revoke. |
| categories | Todas as categorias do banner publicado e só elas, com true ou false. As obrigatórias sempre true. |
| configVersion | Versão do banner que a pessoa viu. |
Corpo em application/json, até 4.096 bytes, sem campos extras: campo desconhecido é 400.
Guarde o consentId: é o recibo. O registro é gravado com source api. IP, navegador e sistema ficam vazios, porque quem chama é o seu servidor, não o visitante.
Sem idempotência na versão 1: reenviar depois de um tempo esgotado pode gravar a mesma decisão duas vezes, com recibos diferentes.
O registro
| Campo | Significado |
|---|---|
| consentId | Recibo, UUID. |
| domain | Domínio do banner. |
| visitorId | Identificador do visitante; null quando o registro foi anonimizado a pedido do titular. |
| action | accept_all, reject_all, partial, revoke. |
| categories | Escolha por categoria, na ordem do banner. |
| configVersion | Versão do banner que o visitante viu. |
| source | Origem: widget (banner da Trusto), api (esta API) ou holder_request (revogação pelo canal do titular). |
| createdAt | Data e hora do registro, ISO 8601 em UTC. |
| expiresAt | Data e hora em que o consentimento vence, ISO 8601 em UTC. Depois dela, peça de novo. |
| erased | true quando o registro foi anonimizado por pedido de titular. |
Revogar não apaga nada: é um registro novo com action revoke. O estado atual de um visitante num domínio é o registro mais novo dele naquele domínio.
Erros
O corpo do erro é sempre um objeto com o campo error. O 409 traz também version, a versão publicada do banner.
{
"error": "config_outdated",
"version": 3
}| Status | Código | Quando |
|---|---|---|
| 400 | invalid_request | JSON inválido, Content-Type diferente de JSON, campo faltando, extra ou fora do formato. |
| 400 | categories_mismatch | Categorias diferentes das do banner publicado. |
| 400 | required_category_refused | Categoria obrigatória enviada como false. |
| 400 | action_mismatch | A action contradiz as escolhas, como accept_all com recusa ou partial sem recusa. |
| 401 | invalid_api_key | Chave ausente, malformada, de outro ambiente, desconhecida, revogada ou de plano sem a API. Sempre o mesmo código, de propósito. |
| 403 | insufficient_scope | A chave não tem a permissão da rota. |
| 404 | consent_not_found | Recibo inexistente ou de outra organização. |
| 404 | domain_not_found | Domínio sem banner publicado ou de outra organização. |
| 405 | sem código | Método não aceito. O cabeçalho Allow diz quais são. |
| 409 | config_outdated | configVersion diferente da publicada. Mostre o banner de novo com a versão atual. |
| 413 | payload_too_large | Corpo acima do limite. |
| 429 | rate_limited | Limite excedido. Espere e tente de novo. |
| 503 | unavailable | Indisponível no momento. Tente de novo com espera crescente. |
Limites
Em janelas de 1 minuto. Ao receber 429, espere a janela virar antes de tentar de novo.
| Limite | Por minuto |
|---|---|
| Consultas por chave | 600 |
| Registros por chave | 120 |
| Pedidos por endereço IP | 1.200 |
| Chaves recusadas por endereço IP; depois disso, o IP recebe 429 até a janela virar | 30 |
Disponibilidade
GET /health responde ok, sem chave. Qualquer outro caminho responde 404.
Versões
A versão 1 só cresce: campo novo em resposta, rota nova ou permissão nova. O que quebrar uma integração existente, como remover ou renomear um campo, vira a versão 2, com a versão 1 mantida até os clientes migrarem.