O HubDE conecta quem origina duplicatas às escrituradoras autorizadas. O cedente não precisa
aprender o sistema da escrituradora, nem obter certificado digital: ele confere o cadastro,
assina por e-mail, e o HubDE cuida do restante — entrega o cadastro, escritura as duplicatas e
devolve o IUD.Esta documentação descreve uma única integração, consumida pelo sistema que envia cedentes e
duplicatas ao HubDE: um ERP de agente financiador ou um portal do cedente. As duas usam as
mesmas rotas e a mesma credencial; o que muda entre elas está na seção 3.Leia este resumo e, em seguida, o Guia de integração para ERPs e Portais do Cedente, antes
da referência dos endpoints. A referência descreve o formato de cada chamada; o guia descreve a
ordem das chamadas, as garantias exigidas e o tratamento de falhas.1. O que o HubDE resolve#
Para cadastrar um cedente numa escrituradora de duplicatas escriturais e escriturar os títulos
dele, sem o HubDE é preciso aprender o sistema da escrituradora, obter certificado digital,
tratar o manual dela e refazer o cadastro que já existe.1.
o seu sistema envia o cadastro que já possui e recebe um link;
2.
quem abre o link confere os dados, escolhe a escrituradora e submete;
3.
o cedente assina o pacote de adesão por e-mail;
4.
o HubDE entrega o cadastro à escrituradora e passa a aceitar as duplicatas daquele cedente;
5.
o seu sistema envia as duplicatas, consulta o desfecho e recebe o IUD de cada título.
O objeto cadastro é obrigatório no passo 1. A requisição que traz apenas documentoCedente e
tipoPessoa é recusada com 422 cedente.nao_encontrado_no_erp — a falha mais frequente na
primeira integração.2. As chamadas, em ordem#
Cadastro do cedente, em três chamadas: criar a sessão de cadastro, abrir a url devolvida e
consultar a situação. Ciclo da duplicata, em quatro: escriturar, consultar o desfecho, consultar
a situação do cedente e informar a liquidação.Entre o cadastro e a escrituração nada exige chamada sua: o cedente assina, a escrituradora
analisa, e o resultado passa a constar nas consultas.Duplicata de cedente que ainda não está ativo é aceita e fica pendente, em silêncio.
Não é erro e não gera aviso. É por isso que GET /erp/v1/cedentes existe — ela explica o que
a consulta de duplicatas não diz.
Duplicata escriturada não se desfaz. Não existe cancelamento: o título passa a existir no
registro, com identificador único.
As regras completas — idempotência, ciclo de vida dos links, códigos de erro e roteiro de
homologação — estão no guia de integração. Elas não são repetidas aqui, para não existirem em
duas versões.3. Os dois arranjos: quem abre o link, e onde a chave pode estar#
A diferença não é técnica, é quem está do outro lado da tela — e ela determina duas coisas:
para quem vai o link, e onde a sua chave de API pode estar.Agente financiador#
Existe uma contraparte que compra o título: a factoring ou o FIDC. Quem opera é um funcionário
dela.O link de cadastro abre no navegador do operador do ERP.
Não o encaminhe ao cedente. Ele é de uso único, tem prazo curto, e quem o abre primeiro
assume a sessão. O cedente participa depois, apenas para assinar, por convite enviado por
e-mail.
Para acompanhar, o operador usa o link de POST /erp/v1/sessoes-acompanhamento, que lista
todos os cedentes do cliente.
Portal do cedente#
Não há agente financiador na jornada: o parceiro é canal, não contraparte. Quem opera é o
próprio cedente.O link de cadastro abre para o próprio cedente, numa aba nova do portal em que ele já
está autenticado.
Para acompanhar, use GET /erp/v1/cedentes filtrando por documentoCedente. Não encaminhe
o link de acompanhamento ao cedente — ele mostra a carteira inteira do cliente.
A X-Api-Key nunca vai ao navegador do cedente. O escopo que o HubDE garante é o do
cliente da chave, ou seja, todos os cedentes que você enviou; recortar um cedente é papel do
parâmetro documentoCedente, e quem o amarra ao cedente autenticado é você. De posse da
chave, um cedente trocaria o parâmetro e veria a carteira inteira. O desenho é sempre:navegador do cedente → seu backend → HubDE
(sua sessão) (sua chave)
O tipo do cliente é definido no cadastro dele no HubDE, e é ele que determina quem abre o
link. Se você não sabe qual é o seu tipo, pergunte antes de começar — a arquitetura acima
depende disso.4. Convenções#
| Assunto | Regra |
|---|
| Autenticação | Header X-Api-Key em todas as requisições, com uma exceção: GET /catalogo/v1/escrituradoras é público. Não há usuário nem sessão; a credencial é entregue uma única vez, no cadastro. |
| Idempotência | Obrigatória em duas rotas: POST /erp/v1/sessoes-onboarding e POST /erp/v1/duplicatas, pelo header Idempotency-Key. As demais não leem o header. Gere a chave uma vez por envio e guarde-a. |
| Identificação do cedente | CNPJ no padrão alfanumérico da Receita Federal (IN RFB 2.229/2024), ^[0-9A-Z]{12}[0-9]{2}$, quando tipoPessoa é JURIDICA; CPF de 11 dígitos quando é FISICA. Os dígitos verificadores são validados nos dois casos — a conformidade com o padrão não é suficiente. |
| Datas e horas | Sempre em UTC, ISO-8601, com offset explícito +00:00, com ou sem fração de segundo. Utilize um parser de ISO-8601; não compare cadeias. |
| Identificadores de entidade | UUID v7. Isso não se aplica ao X-Correlation-Id, que não é UUID. Trate-o como texto opaco. |
| Erros | RFC 9457 (application/problem+json). Trate pelo membro codigo, não pelo title, que é destinado a leitura humana e pode mudar. As exceções de formato estão no guia de integração. |
| Correlação | Todas as respostas incluem o header X-Correlation-Id, gerado pelo HubDE. Registre-o em log: é a informação solicitada pelo suporte. |
5. Suporte#
Havendo divergência entre esta página e a especificação OpenAPI, a especificação é a
referência. Comunique a divergência antes de implementar. Modificado em 2026-11-19 05:56:56