1. Instruções Gerais
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
      • Consulta o desfecho das duplicatas
      • Informa a liquidação de títulos
    • Acompanhamento
      • Consulta a situação dos cedentes
  1. Instruções Gerais

Como começar

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.
Com o HubDE:
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#

AssuntoRegra
AutenticaçãoHeader 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ênciaObrigató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 cedenteCNPJ 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 horasSempre 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 entidadeUUID v7. Isso não se aplica ao X-Correlation-Id, que não é UUID. Trate-o como texto opaco.
ErrosRFC 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çãoTodas as respostas incluem o header X-Correlation-Id, gerado pelo HubDE. Registre-o em log: é a informação solicitada pelo suporte.

5. Suporte#

inogueira@quicksoft.com.br — informe sempre o X-Correlation-Id da requisição em questão.
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
Próxima página
Integração para ERPs e Portais do Cedente
Built with