Trusto para desenvolvedores

Referência · Versão 1

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.

AmbienteEndereçoPrefixo da chave
Testehttps://api.staging.gettrusto.iotrusto_sk_test_…
Produçãohttps://api.gettrusto.iotrusto_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

GET/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-000000000000

Resposta

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

GET/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

POST/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"
}
CampoRegra
domainNome do domínio como cadastrado, sem https://, porta ou caminho. Precisa ter banner publicado nesta organização.
visitorIdUUID que identifica o visitante no seu sistema. É por ele que o histórico e os pedidos de titular encontram o registro.
actionUm de: accept_all, reject_all, partial, revoke.
categoriesTodas as categorias do banner publicado e só elas, com true ou false. As obrigatórias sempre true.
configVersionVersã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

CampoSignificado
consentIdRecibo, UUID.
domainDomínio do banner.
visitorIdIdentificador do visitante; null quando o registro foi anonimizado a pedido do titular.
actionaccept_all, reject_all, partial, revoke.
categoriesEscolha por categoria, na ordem do banner.
configVersionVersão do banner que o visitante viu.
sourceOrigem: widget (banner da Trusto), api (esta API) ou holder_request (revogação pelo canal do titular).
createdAtData e hora do registro, ISO 8601 em UTC.
expiresAtData e hora em que o consentimento vence, ISO 8601 em UTC. Depois dela, peça de novo.
erasedtrue 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
}
StatusCódigoQuando
400invalid_requestJSON inválido, Content-Type diferente de JSON, campo faltando, extra ou fora do formato.
400categories_mismatchCategorias diferentes das do banner publicado.
400required_category_refusedCategoria obrigatória enviada como false.
400action_mismatchA action contradiz as escolhas, como accept_all com recusa ou partial sem recusa.
401invalid_api_keyChave ausente, malformada, de outro ambiente, desconhecida, revogada ou de plano sem a API. Sempre o mesmo código, de propósito.
403insufficient_scopeA chave não tem a permissão da rota.
404consent_not_foundRecibo inexistente ou de outra organização.
404domain_not_foundDomínio sem banner publicado ou de outra organização.
405sem códigoMétodo não aceito. O cabeçalho Allow diz quais são.
409config_outdatedconfigVersion diferente da publicada. Mostre o banner de novo com a versão atual.
413payload_too_largeCorpo acima do limite.
429rate_limitedLimite excedido. Espere e tente de novo.
503unavailableIndisponí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.

LimitePor minuto
Consultas por chave600
Registros por chave120
Pedidos por endereço IP1.200
Chaves recusadas por endereço IP; depois disso, o IP recebe 429 até a janela virar30

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.