Enviar manifestações - V2

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

Um 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 ShipayID 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:

Janelarejectedacceptedcommercial_annotation
Do 1º ao 10º dia útilPermitidoPermitidoPermitido
Do 11º ao 15º dia útilBloqueado (TEMPORAL_WINDOW_EXCEEDED)PermitidoPermitido
A partir do 16º dia útilBloqueado (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 atualacceptedrejectedcommercial_annotation
pendingPermitidoPermitidoPermitido
accepted ou tacit_acceptanceBloqueado (INMA_RULE_VIOLATION)Bloqueado (INMA_RULE_VIOLATION)Permitido
rejectedPermitidoBloqueado (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çãoStatusstatements[]errors[]
Todos os itens válidos202PreenchidoVazio
Parte válida, parte recusada207Só os recebidosSó os recusados
Todos os itens recusados422VazioPreenchido
Falha do lote inteiro422—— (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_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 com status pending) e acione o suporte da Shipay.
Body Params
statements
array of objects
required
length between 1 and 100

Manifestações do lote, de 1 a 100 itens.

statements*
Headers
string

Identificador de rastreio da requisição, ecoado nos logs da Shipay. Quando não enviado, a Shipay gera um.

Responses

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json