Recebe manifestações do sacado (aceite, recusa ou anotação comercial) sobre suas duplicatas.
A rota valida o lote, grava as manifestações e responde em seguida. O envio à registradora acontece depois, de forma assíncrona.
O 202 confirma o recebimento, não o envio
202 confirma o recebimento, não o envioUm 202 significa que a Shipay recebeu e validou a manifestação. Ele não significa que a manifestação já chegou à registradora.
A registradora opera das 8h às 20h. Uma manifestação aceita aqui perto do fim do prazo pode ser recusada no momento do envio, porque o prazo venceu enquanto ela aguardava na fila. Nesse caso, a manifestação termina com status error e o motivo em failure_reason. O resultado final deve ser acompanhado pela consulta unitária ou pela listagem.
Identificação da duplicata
Cada item deve trazer exatamente um identificador da duplicata:
| ID da Shipay | ID da registradora |
|---|---|
registered_invoice_id (UUID) | iud |
Enviar os dois no mesmo item, ou nenhum, retorna 422 — mesmo que os dois apontem para a mesma duplicata. Na resposta, cada manifestação aceita traz os dois identificadores preenchidos.
Prazo para manifestação
A janela é contada em dias úteis a partir da data de emissão da duplicata (ou da data de cadastro na Shipay, quando a duplicata não tem data de emissão), considerando feriados nacionais e o horário de Brasília:
| Janela | rejected | accepted | commercial_annotation |
|---|---|---|---|
| Do 1º ao 10º dia útil | Permitido | Permitido | Permitido |
| Do 11º ao 15º dia útil | Bloqueado (TEMPORAL_WINDOW_EXCEEDED) | Permitido | Permitido |
| A partir do 16º dia útil | Bloqueado (TEMPORAL_WINDOW_EXCEEDED) | Bloqueado (TEMPORAL_WINDOW_EXCEEDED) | Permitido |
A registradora recebe manifestações das 8h às 20h. O que chega fora desse horário fica pending e é enviado no próximo dia útil. Se um aceite ou uma recusa ainda estiver aguardando o envio a partir do 16º dia útil após a emissão, ele termina com status error e o motivo em failure_reason. O mesmo ocorre se a duplicata virar tacit_acceptance enquanto a manifestação aguarda na fila.
Compatibilidade com a manifestação anterior
A nova manifestação é comparada com o statement_status atual da duplicata:
statement_status atual | accepted | rejected | commercial_annotation |
|---|---|---|---|
pending | Permitido | Permitido | Permitido |
accepted ou tacit_acceptance | Bloqueado (INMA_RULE_VIOLATION) | Bloqueado (INMA_RULE_VIOLATION) | Permitido |
rejected | Permitido | Bloqueado (INMA_RULE_VIOLATION) | Permitido |
Enquanto houver um aceite ou uma recusa em andamento (pending ou processing) para a duplicata, um novo aceite ou recusa é bloqueado (STATEMENT_ALREADY_IN_PROGRESS). Anotação comercial continua permitida.
Situação da duplicata
Não é possível se manifestar sobre duplicata liquidada (finished), cancelada (cancelled), ainda não registrada na registradora ou com erro no registro (DISALLOWED_REGISTERED_INVOICE_STATUS).
Resultado do lote
Cada item é validado separadamente. Os itens não recebidos aparecem em errors[], com o item identificado por field (posição no lote), o valor recusado em value, o motivo em code e a descrição em detail.
Por que field traz a posição do item, e não o IUD: o field aponta o campo exato do payload que foi recusado (statements.<i>.<campo>), no mesmo formato dos erros de validação do payload e alinhado ao padrão RFC 7807 (Problem Details) adotado nas APIs da Shipay. Assim, o erro é localizado sem ambiguidade, mesmo quando a mesma duplicata aparece em mais de um item do lote ou quando o item foi enviado pelo registered_invoice_id. O valor recusado vem em value e o motivo em code, o que permite traduzir o erro para uma mensagem em tela.
| Situação | Status | statements[] | errors[] |
|---|---|---|---|
| Todos os itens válidos | 202 | Preenchido | Vazio |
| Parte válida, parte recusada | 207 | Só os recebidos | Só os recusados |
| Todos os itens recusados | 422 | Vazio | Preenchido |
| Falha do lote inteiro | 422 | — | — (erro no formato RFC 7807) |
Algumas falhas recusam o lote inteiro, sem processar nenhum item, nem os válidos:
- payload inválido ou com mais de 100 itens;
- aceite e recusa para a mesma duplicata no mesmo lote;
- o mesmo tipo de manifestação repetido para a mesma duplicata no mesmo lote.
Aceite ou recusa junto com anotação comercial para a mesma duplicata é permitido: os dois seguem como itens separados.
Motivos em failure_reason
failure_reasonfailure_reason é uma descrição em inglês do motivo e não um enum; use status para decidir o fluxo. Valores esperados:
Statement deadline expired before it could be submitted to the CSD: o prazo (16º dia útil ou aceite tácito) venceu enquanto a manifestação aguardava na fila;CSD did not return an external process id;- a mensagem devolvida pela registradora.
O detail vem em inglês e é apenas informativo; use o code na integração.
Reenvio e concorrência
- Reenvio idêntico: dentro de uma janela de tempo após o envio, o mesmo lote reenviado pelo mesmo sacado devolve a resposta do primeiro envio, sem criar outro processamento. Vale apenas para lotes com pelo menos um item recebido; passada a janela, o reenvio é tratado como um novo lote.
- Envios simultâneos: enquanto um lote do mesmo sacado está sendo validado, um novo envio retorna
409. Aguarde alguns instantes e reenvie. - Falha ao enfileirar: se a Shipay não conseguir enfileirar o envio à registradora, a resposta é
502. As manifestações podem ter sido gravadas mesmo assim, sem envio à registradora. Não reenvie o lote: consulte a listagem (elas aparecem comstatuspending) e acione o suporte da Shipay.

