Enviar evento pelo navegador
Registra um evento de captura usando o token publicável. É o endpoint que o snippet chama, e você pode chamá-lo direto se preferir não carregar o script.
Endpoint
Seção intitulada “Endpoint”https://api.rapidchargeback.com/api/v1/capture/{token}/eventsAutenticação
Seção intitulada “Autenticação”Nenhuma. O token publicável na URL identifica o merchant.
Content-Type: application/jsonO snippet manda o mesmo JSON como text/plain, que o navegador envia sem consulta prévia de CORS. Os dois tipos são aceitos.
O token não é segredo e pode ficar no HTML da sua loja. Ele só permite escrever, e o evento só vira evidência se corresponder a um pedido real seu.
Parâmetros de URL
Seção intitulada “Parâmetros de URL”| Campo | Tipo | Descrição |
|---|---|---|
token | string | Token publicável do merchant, gerado no painel |
Corpo da requisição
Seção intitulada “Corpo da requisição”| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
type | string (enum) | checkout, terms_acceptance, access_log ou usage_log | Sim |
order_ref | string ou número | Identificador do pedido no seu sistema, até 100 caracteres | Sim |
event_id | string ou número | Identificador do evento, gerado por você, até 64 caracteres | Sim |
payload | objeto | Dados do fato, com campos de lista fechada | Não |
A referência completa dos valores aceitos está em Tipos e payload.
Dois pontos específicos deste canal:
event_idé obrigatório aqui. Gere um UUID por eventocaptured_atenviado no corpo é ignorado. A Rapid registra o horário de chegada. Para informar o horário do fato, use o canal servidor
Os tipos delivery_confirmation, scan e delivery_gps não existem neste canal: são fatos da sua operação, não do navegador do comprador.
Limite de chamadas
Seção intitulada “Limite de chamadas”120 requisições por minuto, por IP de origem e token. É folgado para um checkout real e aperta quem estiver usando o token fora do seu site. Contar também pelo token evita que compradores de lojas diferentes atrás do mesmo IP (rede móvel) dividam o mesmo limite.
Além disso, cada merchant tem um teto de eventos do navegador esperando a transação aparecer. Acima dele, o evento responde 429 TOO_MANY_PENDING_EVENTS até a fila andar. Uso normal não chega perto: o teto existe para o caso de alguém mandar pedidos inventados com o seu token. O envio pelo servidor tem um teto separado, então esse abuso não barra os eventos que o seu backend manda.
Validações
Seção intitulada “Validações”| Regra | Resposta |
|---|---|
| Token desconhecido, inativo ou sem merchant | 404 NOT_FOUND |
type ausente, ou fora dos quatro aceitos neste canal | 422 VALIDATION_ERROR: invalid_type |
order_ref ausente, vazio ou acima de 100 caracteres | 422 VALIDATION_ERROR: invalid_order_ref |
event_id ausente, vazio ou acima de 64 caracteres | 422 VALIDATION_ERROR: invalid_event_id |
device_id acima de 100 caracteres, device_fingerprint acima de 255 ou outro campo de texto do payload acima de 512 | 422 VALIDATION_ERROR: payload_too_large |
| Evento vindo de um site que não está entre os sites em que o token vale (ver) | 403 ORIGIN_NOT_ALLOWED |
| Acima de 120 requisições por minuto | 429 Too Many Requests |
| Merchant com eventos demais esperando a transação | 429 TOO_MANY_PENDING_EVENTS |
| Recebimento da captura temporariamente indisponível | 503 CAPTURE_TEMPORARILY_UNAVAILABLE, com Retry-After |
No 503, reenvie o evento depois dos segundos do header Retry-After. Com o mesmo event_id, o reenvio nunca duplica a evidência.
Não existe erro para order_ref inexistente. O evento é aceito, fica na fila e é descartado se nenhuma transação corresponder dentro da janela de correlação. Ver Janela de correlação.
Exemplo de requisição
Seção intitulada “Exemplo de requisição”curl -X POST https://api.rapidchargeback.com/api/v1/capture/seu_token_publicavel/events \ -H "Content-Type: application/json" \ -d '{ "type": "terms_acceptance", "order_ref": "TXN-2026-001", "event_id": "019b0000-1111-7000-8000-000000000001", "payload": { "url": "https://loja.exemplo.com/checkout" } }'Evento de checkout com identificação do aparelho:
curl -X POST https://api.rapidchargeback.com/api/v1/capture/seu_token_publicavel/events \ -H "Content-Type: application/json" \ -d '{ "type": "checkout", "order_ref": "TXN-2026-001", "event_id": "019b0000-1111-7000-8000-000000000002", "payload": { "device_id": "8kJ2mQvR1nZxYb0T", "device_fingerprint": "8kJ2mQvR1nZxYb0T", "fp": "pro", "fp_request_id": "1712059781234.Xk9Lp2" } }'Exemplos de resposta
Seção intitulada “Exemplos de resposta”Sucesso (202)
Seção intitulada “Sucesso (202)”{ "accepted": true }202 quer dizer que o evento entrou na fila, não que já virou evidência. A correlação com a transação acontece depois.
Erro: token desconhecido (404)
Seção intitulada “Erro: token desconhecido (404)”{ "error": { "code": "NOT_FOUND" } }Erro: tipo não disponível neste canal (422)
Seção intitulada “Erro: tipo não disponível neste canal (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_type" }}Erro: event_id ausente (422)
Seção intitulada “Erro: event_id ausente (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_event_id" }}Erro: campo de payload longo demais (422)
Seção intitulada “Erro: campo de payload longo demais (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "payload_too_large" }}