1. Duplicatas
HubDE
  • Instruções Gerais
    • Como começar
  • Integração para ERPs e Portais do Cedente
    • Integração para ERPs e Portais do Cedente
    • Cadastro do cedente
      • Cria a sessão de cadastro do cedente
      • Cria a sessão de acompanhamento
      • Consulta o cliente da credencial
      • Lista as escrituradoras disponíveis
    • Duplicatas
      • Envia as duplicatas de uma operação
        POST
      • Consulta o desfecho das duplicatas
        GET
      • Informa a liquidação de títulos
        POST
    • Acompanhamento
      • Consulta a situação dos cedentes
  1. Duplicatas

Envia as duplicatas de uma operação

POST
/erp/v1/duplicatas
Envie o lote assim que a operação for efetivada e o conjunto de duplicatas estiver
fechado — número, valor de face, vencimento, sacado e chave da nota fiscal não mudam mais.
A resposta não traz o IUD. Ele ainda não existe: quem o atribui é a Escrituradora, e o
Hub o devolve depois. O que volta agora é o protocolo do lote, que é a sua própria
Idempotency-Key, e um desfecho por duplicata.
Lote parcial é resposta de sucesso. Se 3 de 50 duplicatas forem recusadas, as 47
válidas entram e o status é 207: cada item traz situacao, e a recusada traz campo e
codigoErro. Corrija as 3 no ERP e envie apenas elas, com uma Idempotency-Key inédita — não
reenvie o lote inteiro.
Reenviar o mesmo lote não escritura nada em dobro. Com a mesma Idempotency-Key, a
resposta original é devolvida tal e qual. Com chave inédita, cada duplicata já conhecida
volta como ja_recebida, com o duplicataId que ela já tinha — a identidade é a tripla
cliente, cedente e referencia, e só ela. O conteúdo não é atualizado: divergência num
reenvio é tratada como exceção, não como alteração.
A exceção é a duplicata recusada. Reenviá-la com o cadastro corrigido a devolve ao
andamento: a situação volta aceita, com o mesmo duplicataId, e o conteúdo que
chegou agora substitui o anterior. É assim que se corrige uma recusa — sem isso, corrigir
no seu ERP e reenviar não teria efeito algum. numeroFatura e parcela são a
única parte que não muda no caminho de volta.
A referencia é sua e tem de ser estável. É ela que correlaciona a resposta, o IUD que
chega depois e o título no seu banco. Única por cedente dentro do seu cliente.
Duas recusas nascem de repetição dentro do mesmo lote.
referencia_repetida_no_lote (campo referencia) quando o mesmo cedente aparece duas
vezes com a mesma referencia; e fatura_parcela_repetida_no_lote (campo
numeroFatura) quando o mesmo cedente aparece duas vezes com o mesmo numeroFatura
e a mesma parcela. A unicidade vale dentro do POST.

Requisição

Parâmetros Header

Parâmetros Bodyapplication/jsonNecessário

Examples

Respostas

🟢201
application/json
O lote inteiro entrou. Nenhuma duplicata recusada.
Headers

Bodyapplication/json

🟢207
🟠400
🟠409
🟠401NaoAutenticada
🟠403Suspensa
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/erp/v1/duplicatas' \
--header 'Idempotency-Key: 018f3a7c-8e2b-7c4a-9d61-2f5b8c7e4a10' \
--header 'Content-Type: application/json' \
--data-raw '{
    "duplicatas": [
        {
            "documentoCedente": "11222333000181",
            "referencia": "NF 12345 01",
            "numeroFatura": "FAT 2026 001",
            "parcela": 1,
            "tipo": 1,
            "vencimento": "2026-12-31",
            "emitidaSacadorEm": "2026-10-01",
            "valorTotalFatura": 1500,
            "valorDesconto": 100,
            "valor": 1400,
            "pracaPagamento": "4209102",
            "sacado": {
                "documento": "63301281000132",
                "nome": "COMERCIAL BOA VISTA LTDA",
                "logradouro": "Rua das Amostras",
                "numero": "100",
                "bairro": "Centro",
                "cep": "89201000",
                "municipio": "Joinville",
                "uf": "SC",
                "email": "contas@boavista.com.br"
            },
            "documentosFiscais": [
                {
                    "tipo": 3,
                    "chave": "35260411222333000181550010000000011000000017",
                    "numero": "1",
                    "serie": "1"
                }
            ],
            "instrumentosPagamento": [
                {
                    "tipo": 2,
                    "boletoLinha": "34191790010104351004791020150008291070026000",
                    "boletoTipo": 1
                }
            ]
        }
    ]
}'
Response Response Example
201 - Exemplo 1
{
    "protocolo": "string",
    "recebidas": 0,
    "aceitas": 0,
    "recusadas": 0,
    "duplicatas": [
        {
            "posicao": 0,
            "referencia": "string",
            "situacao": "aceita",
            "duplicataId": "4c989e37-87c2-4506-92e7-61e689172999",
            "codigoErro": "string",
            "mensagemErro": "string",
            "campo": "string"
        }
    ]
}
Modificado em 2026-11-19 05:54:58
Página anterior
Lista as escrituradoras disponíveis
Próxima página
Consulta o desfecho das duplicatas
Built with