# Trust7 API — contexto canônico para agentes de IA

> Versão do contrato: 1.3.0
> Base URL de produção: https://trust7.dev/v1
> OpenAPI completo: https://docs.trust7.dev/openapi.yaml
> Documentação humana: https://docs.trust7.dev/

## Objetivo

Use este documento para integrar um backend de seller à API de pagamentos Trust7. Não invente
endpoints, campos, status ou capacidades. Em caso de divergência, o OpenAPI é o contrato estrutural;
pare e reporte qualquer conflito entre ele e este guia.

## Regras invariantes

1. TRUST7_API_KEY é segredo de backend. Nunca deve ir para browser, aplicativo distribuído, HTML,
   repositório, logs ou analytics.
2. Autenticação: `Authorization: Bearer key_xxxxx.sk_xxxxx`.
3. Base URL: `https://trust7.dev/v1`.
4. Corpos e respostas usam JSON UTF-8. Use `Content-Type: application/json`.
5. Valores monetários são inteiros na menor unidade. `2590` significa R$ 25,90. Nunca envie float.
6. Moeda usa ISO-4217 em maiúsculas; para Pix, `BRL`.
7. IDs são strings opacas. Não analise prefixos nem imponha tamanho local.
8. Timestamps são ISO 8601 UTC.
9. Ignore campos desconhecidos em respostas para permitir evolução compatível.
10. Todo POST financeiro exige `Idempotency-Key` de 8 a 255 caracteres.

## Antes de oferecer Pix

Faça `GET /payment-methods` com Bearer. Localize o item `method: "pix"`. Ofereça Pix somente se
`enabled` for `true`. Sem adquirente Pix homologada e ativa, `POST /payments` responde HTTP 424 com
`error.code = "payment_method_unavailable"`. Não assuma disponibilidade por ambiente ou data.

## Criar Pix

Request:

```http
POST /payments HTTP/1.1
Host: trust7.dev
Authorization: Bearer SUA_CHAVE_SECRETA
Content-Type: application/json
Accept: application/json
Idempotency-Key: order-pedido-789-pix-v1

{
  "amount": 2590,
  "currency": "BRL",
  "payment_method": {
    "type": "pix",
    "expires_in_seconds": 1800
  },
  "customer": {
    "reference": "cliente-123",
    "name": "Ana Silva",
    "email": "cliente@example.com",
    "phone": "+5511999999999"
  },
  "metadata": {
    "order_id": "pedido-789"
  }
}
```

`expires_in_seconds` é opcional, mínimo 60, máximo 86400 e padrão 3600.
`customer` e `metadata` são opcionais. Envie `customer.name`, `customer.email` e `customer.phone`
quando disponíveis para preencher corretamente a lista e o CSV de clientes do seller. Metadata
aceita strings e não deve conter segredos.

Resposta Pix normal: HTTP 202, `status = "pending_action"`, `payment_method.type = "pix"`,
`next_action.type = "pix_qr_code"`, `next_action.qr_code` com o Pix Copia e Cola e
`next_action.expires_at` em ISO 8601. Persista pelo menos `id`, `status`, `sequence`, `amount`,
`metadata.order_id` e `expires_at`. O frontend recebe somente o necessário, por exemplo:
`payment_id`, `status`, `qr_code`, `expires_at`.

## Idempotência

A chave representa uma operação lógica, não uma tentativa HTTP. Gere-a uma vez e salve-a junto ao
pedido local. Se houver timeout, conexão interrompida ou HTTP 5xx, repita exatamente o mesmo corpo e
a mesma chave. A Trust7 devolve a resposta original e pode incluir `Idempotency-Replayed: true`.
Reutilizar a mesma chave com corpo diferente retorna HTTP 409. Não gere uma nova cobrança apenas
porque a resposta da primeira tentativa não chegou.

## Consultar pagamento

`GET /payments/{id}` não exige idempotência. Use para recuperação, reconciliação e tela de detalhe.
Não faça polling agressivo; webhooks são o mecanismo principal de atualização.

Status importantes:
- `pending_action`: aguarda pagamento Pix; não liberar pedido.
- `captured`: pagamento confirmado; pode liberar pedido.
- `expired`, `canceled`, `failed`: estados finais sem confirmação; não liberar pedido.
- `partially_refunded`, `refunded`: conciliar `amount_refunded`.
- `blocked_med`: valor Pix bloqueado pelo MED; bloquear disponibilidade e acompanhar eventos MED.

## Webhooks

Cadastre com `POST /webhook-endpoints`:

```json
{
  "url": "https://api.sualoja.com/webhooks/trust7",
  "events": ["payment.captured", "payment.expired", "payment.canceled", "payment.failed"]
}
```

O endpoint precisa ser público; em produção a Trust7 recusa localhost e endereços privados. A
resposta 201 contém `secret`, exibido uma única vez. `GET /webhook-endpoints` omite o segredo.
Lista de eventos vazia ou `["*"]` assina todos os eventos. Remova com
`DELETE /webhook-endpoints/{id}`. Consulte entregas com `GET /webhook-deliveries?limit=50`.

Envelope:

```json
{
  "id": "evt_01J8ZQ7",
  "type": "payment.captured",
  "sequence": 2,
  "created_at": "2026-08-13T00:02:10Z",
  "data": { "object": { "id": "pay_01J8ZQ5MB2", "status": "captured", "sequence": 2 } }
}
```

Entrega é at-least-once e a ordem não é garantida. Deduplicate de forma transacional por `event.id`.
Para o mesmo objeto, aplique somente `sequence` maior que a última já processada. Confirme pedido
somente para `payment.captured`, nunca apenas por `pending_action` ou presença de QR Code.

Assinatura: header HTTP `Trust7-Signature` no formato `t=TIMESTAMP,v1=HEX`.
Material assinado: bytes ASCII do timestamp decimal, depois ponto (`.`), depois o corpo HTTP cru.
Digest: HMAC-SHA256 com o secret do endpoint, codificado como hexadecimal minúsculo.

Validação obrigatória:
1. Capture o corpo cru antes do parse JSON.
2. Extraia `t` e `v1`.
3. Recuse timestamp inválido ou com diferença superior a 300 segundos.
4. Calcule HMAC-SHA256(secret, timestamp + "." + raw_body).
5. Compare em tempo constante.
6. Faça parse do JSON apenas após assinatura válida.
7. Persista deduplicação e mudança de estado.
8. Responda qualquer 2xx rapidamente; execute trabalho pesado fora do request.

Política de retry de webhook: timeout de 5 segundos; até 10 tentativas; backoff exponencial com
jitter e teto de 30 minutos. Há retry em erro de rede, timeout, HTTP 408, 429 e 5xx. Outros 4xx
encerram a entrega. Redirecionamentos não são seguidos.

Eventos de pagamento: `payment.authorized`, `payment.captured`, `payment.canceled`,
`payment.failed`, `payment.pending_action`, `payment.expired`, `payment.blocked_med`,
`payment.med_released`, `payment.med_debited`.
Outros: `refund.created`, `refund.failed`, `dispute.opened`, `dispute.won`, `dispute.lost`,
`payout.paid`, `payout.failed`, `payout.returned`, `seller.status_changed`.

## Erros e retry de API

Envelope:
`{"error":{"type":"...","code":"...","message":"...","param":"...","request_id":"req_..."}}`

- 400: erro de validação; não repetir sem corrigir.
- 401: chave ausente/inválida/revogada; corrigir credencial.
- 403: sem permissão ou conta bloqueada; não repetir automaticamente.
- 404: recurso não existe no escopo da conta.
- 409: conflito de estado ou idempotência; analisar `error.code`.
- 424: método/adquirente indisponível; não repetir em loop; consultar `/payment-methods`.
- 429: repetir após `Retry-After`, com backoff e jitter.
- 500+: repetir com backoff e a mesma Idempotency-Key/corpo.

## Testes mínimos exigidos

1. Pix criado com sucesso e dados necessários devolvidos ao frontend.
2. Replay com mesma Idempotency-Key não duplica pedido local nem pagamento.
3. Mesmo ID idempotente com corpo diferente é tratado como 409.
4. Pix desabilitado/HTTP 424 tem mensagem recuperável e não entra em retry infinito.
5. Webhook com assinatura inválida é recusado.
6. Webhook com timestamp antigo é recusado.
7. Evento duplicado não aplica efeito duas vezes.
8. Evento de sequence menor não regride estado.
9. `payment.captured` confirma pedido; `expired`, `canceled` e `failed` não confirmam.
10. 429 e 5xx usam backoff; segredos e dados pessoais não aparecem nos logs.

## Endpoints principais

- `GET /payment-methods`
- `POST /payments`
- `GET /payments`
- `GET /payments/{id}`
- `POST /payments/{id}/capture`
- `POST /payments/{id}/void`
- `POST /payments/{id}/refunds`
- `POST /webhook-endpoints`
- `GET /webhook-endpoints`
- `DELETE /webhook-endpoints/{id}`
- `GET /webhook-deliveries?limit=50`
Leia https://docs.trust7.dev/openapi.yaml para schemas, limites e endpoints adicionais.