Enviar evento pelo servidor

Registra um evento de captura pelo seu backend, com as mesmas credenciais das outras APIs. É o canal para fatos que não acontecem no navegador: entrega confirmada, leitura de rastreio, coordenada de entrega, e para qualquer evento que você precise reenviar ou datar.

Endpoint

POST https://api.rapidchargeback.com/api/v1/capture/events

Autenticação

Basic Auth com client_id:client_secret. Ver Autenticação.

Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

Não use o token publicável aqui. A empresa vem da credencial, por isso este canal pode gravar dado de aparelho sem a validação exigida no navegador.

Corpo da requisição

Campo	Tipo	Descrição	Obrigatório
`merchant_id`	string (UUID)	Merchant a que o evento pertence, dentro da sua empresa (ver Listar merchants)	Sim
`type`	string (enum)	Os quatro tipos do navegador mais `delivery_confirmation`, `scan` e `delivery_gps`	Sim
`order_ref`	string	Identificador do pedido no seu sistema, até 100 caracteres	Sim
`event_id`	string	Identificador do evento, até 64 caracteres. Omitido, a Rapid gera um	Não
`payload`	objeto	Dados do fato, com campos de lista fechada	Não
`captured_at`	string (ISO 8601)	Quando o fato aconteceu. Omitido, vale o horário da chamada	Não

A referência completa dos valores aceitos está em Tipos e payload.

Três diferenças em relação ao canal navegador:

merchant_id é obrigatório, porque a credencial identifica a empresa e não o merchant
captured_at é respeitado, então uma rotina em lote pode informar o horário real de cada fato
event_id é opcional, mas mande o seu: é o que torna o reenvio seguro

Idempotência

Reenviar a mesma chamada com o mesmo event_id não duplica a evidência. É o comportamento esperado em retentativa por timeout ou resposta perdida.

Se você omitir o event_id, cada chamada gera um identificador novo, e a mesma chamada repetida vira dois registros.

Validações

Regra	Resposta
Credencial ausente ou inválida	`401 UNAUTHORIZED`
`merchant_id` ausente	`422 VALIDATION_ERROR`: merchant_id required
`type` ausente ou fora do enum	`422 VALIDATION_ERROR`: invalid_type
`order_ref` ausente, vazio ou acima de 100 caracteres	`422 VALIDATION_ERROR`: invalid_order_ref
`event_id` acima de 64 caracteres	`422 VALIDATION_ERROR`: invalid_event_id
Campo de texto do `payload` acima de 512 caracteres	`422 VALIDATION_ERROR`: payload_too_large

merchant_id de outra empresa não acusa erro na chamada: o evento é aceito e descartado na correlação, porque a transação é procurada dentro da sua empresa. O mesmo vale para order_ref inexistente.

Exemplo de requisição

Entrega confirmada:

curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_confirmation",
    "order_ref": "TXN-2026-001",
    "event_id": "entrega-TXN-2026-001",
    "payload": { "carrier": "correios", "tracking": "AA123456789BR" },
    "captured_at": "2026-04-03T11:20:00Z"
  }'

Coordenada da entrega:

curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_gps",
    "order_ref": "TXN-2026-001",
    "event_id": "gps-TXN-2026-001",
    "payload": { "lat": -23.5614, "lng": -46.6559 },
    "captured_at": "2026-04-03T11:20:00Z"
  }'

Exemplos de resposta

Sucesso (202)

{ "accepted": true }

202 quer dizer que o evento entrou na fila. A correlação com a transação acontece depois, pelo order_ref.

Erro: credencial ausente (401)

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Erro: `merchant_id` ausente (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "merchant_id required"
  }
}

Erro: tipo inválido (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "invalid_type"
  }
}

Captura ou evidência

Os dois canais registram fato numa transação, e a escolha é simples:

Situação	Use
A transação já está na Rapid e você tem o UUID dela	`POST /evidence`
Você tem só o seu identificador de pedido, ou o fato acontece antes do envio da transação	este endpoint
O fato precisa de campo fora da lista fechada de payload	`POST /evidence`, que aceita payload livre