1. Integração para ERPs e Portais do Cedente
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. Integração para ERPs e Portais do Cedente

Integração para ERPs e Portais do Cedente

Contrato entre o sistema que integra e o HubDE, o Hub de Duplicatas Escriturais do Grupo Quick Soft.

Este contrato é consumido pelo sistema que envia cedentes e duplicatas ao HubDE.

1. Os dois arranjos, e por que isso muda a sua integração#

As rotas são as mesmas para todo mundo. O que muda é quem está do outro lado da tela,
e isso decide duas coisas: quem abre o link e onde a sua chave de API pode estar.
Agente financiador — o cliente do HubDE é uma factoring ou FIDC que compra o título
e roda um ERP, como o QProf. Quem opera é um funcionário dela; o cedente participa
apenas para assinar.
Portal do cedente — o cliente do HubDE é um parceiro que mantém um portal onde o
próprio cedente entra, importa os títulos dele e clica para mandar o próprio
cadastro e escriturar as próprias duplicatas. Não há agente financiador na jornada: o
parceiro é canal, não contraparte.
Seu cliente é cadastrado no HubDE com um desses dois tipos, e é ele que determina quem abre
o link. Se você não sabe qual é o seu, pergunte antes de começar — a seção 3 muda inteira.
Integra um portal do cedente? Leia também o
GUIA-INTEGRACAO-PORTAL-DO-CEDENTE.md, que percorre o fluxo desse arranjo de ponta a
ponta. Esta especificação é o contrato; aquele guia é o roteiro.

2. O que o HubDE resolve#

Alguém precisa cadastrar um cedente numa escrituradora e escriturar as duplicatas dele.
Sem o HubDE, isso exige aprender o sistema da escrituradora, obter certificado digital e
tratar o manual dela. Com o HubDE, você envia o cadastro que já tem e recebe um link:
quem abre confere os dados, escolhe a escrituradora e submete o pacote de adesão. Depois
disso, as duplicatas vão por JSON e o IUD volta por consulta.

3. Fluxo e quem abre o link#

O envio é igual nos dois arranjos — POST /erp/v1/sessoes-onboarding devolve uma url
com prazo curto e de uso único. O que muda é para quem essa url vai.
No agente financiador: a tela é preenchida pelo operador do seu ERP, e a url
abre no navegador dele. Não a encaminhe ao cedente — ele participa depois, só para
assinar, por convite que chega por e-mail.
No portal do cedente: quem abre a url é o próprio cedente, numa aba nova do
portal em que ele já está logado. É ele quem confere, completa o que falta, escolhe a
escrituradora e submete — e depois assina, pelo mesmo convite por e-mail.
Em ambos: após a submissão, o cedente assina, a escrituradora analisa e o resultado passa
a constar nas consultas — nenhuma dessas transições exige chamada sua. Para acompanhar,
há dois caminhos, e eles servem a públicos diferentes:
GET /erp/v1/cedentes — rota de máquina, filtrável por documentoCedente. É a que
um portal do cedente usa para mostrar a cada cedente a situação dele.
POST /erp/v1/sessoes-acompanhamento — link de tela. Sem corpo, lista todos os
cedentes deste cliente, e serve ao operador de um agente financiador. Com
documentoCedente no corpo, mostra só aquele cedente — é o link que se entrega ao
próprio cedente, num portal do cedente.

4. O ciclo da duplicata#

Cadastrar o cedente é a porta de entrada; o que se faz depois dela é escriturar. São
quatro chamadas, e elas se encadeiam:
1.
Escriturar — POST /erp/v1/duplicatas. Um lote de até 500 duplicatas, com
Idempotency-Key. A resposta é 201 quando nada foi recusado, ou 207
quando ao menos uma duplicata foi recusada — inclusive quando todas foram.
Trate os dois.
2.
Consultar o desfecho — GET /erp/v1/duplicatas. É aqui que o IUD chega. A
escrituração é assíncrona: o POST devolve em protocolo a sua própria
Idempotency-Key, ecoada — o HubDE não inventa identificador de lote —, e o
identificador do título só existe depois que a escrituradora o constitui. Não confunda
com o protocolo do GET /erp/v1/duplicatas, que é o protocolo da escrituradora para
aquela duplicata. Ninguém avisa você — quem pergunta é o seu sistema, por varredura.
3.
Consultar o cadastro do cedente — GET /erp/v1/cedentes. Explica o passo
anterior: enquanto o cedente não está ativo, a duplicata dele fica pendente em
silêncio, esperando.
4.
Informar o pagamento — POST /erp/v1/duplicatas/liquidacoes, quando o título for
pago. Só duplicata já escriturada aceita liquidação.
Três coisas que decidem a qualidade da integração:
A referencia é sua, e é por ela que você reencontra o título. O id é do HubDE e
não significa nada do seu lado; o iud só existe depois do desfecho. Use um valor
estável e único por cedente.
Aceito não é escriturado. O sucesso do envio diz que o HubDE recebeu, não que a
escrituradora constituiu o título. Só a consulta do desfecho afirma isso.
Duplicata escriturada não se desfaz. Não existe cancelamento: o título passa a
existir no registro, com identificador único. Confirme antes de enviar.
Varra por atualizadoDesde, nas duas consultas. Guarde o maior atualizadoEm que
recebeu e devolva-o na chamada seguinte. O corte é inclusivo de propósito — dois
registros podem ter o mesmo instante, e um corte exclusivo perderia o segundo para
sempre. Em troca a última página repete, o que é inofensivo porque você grava por
referencia ou por documentoCedente.

5. Conteúdo do cadastro#

Envie todos os dados disponíveis. O HubDE aceita cadastro incompleto: cada campo
ausente vira pendência na tela de conferência — apresentada ao operador do ERP ou ao
próprio cedente, conforme o arranjo da seção 1.
O conteúdo mínimo é o que a assinatura exige:
documentoCedente e tipoPessoa;
origem — o ERP de procedência e o código do cedente nele, para conciliação
posterior pelo suporte;
identificação de quem assina: pessoa jurídica, ao menos um representante com nome,
CPF e e-mail válidos; pessoa física, o contato.email do próprio cedente.
Sem signatário não há destinatário para o convite, e aceitar a requisição abriria o
vínculo de um cedente sem meio de assinatura. Isso é 400, e não pendência de tela.
Dado inválido é adaptado, não recusado, e a natureza do campo decide como.
Identificador que não serve é removido do cadastro — nunca truncado, porque cortado
ele passa a identificar outro registro. Se o campo for um dos que o cedente pode completar
na tela (razaoSocial ou nome, os seis de endereco — logradouro, numero, bairro,
municipio, uf e cep —, o domicilioBancario e contato.email quando o cedente
é pessoa jurídica), ele volta como pendência. Qualquer outro identificador — telefone, site,
documento de identidade do representante — sai do cadastro em silêncio. contato.email de
pessoa física é a exceção: ele é o endereço do convite de assinatura, e malformado é 400.
Texto descritivo acima do limite é truncado e permanece no cadastro, sem retornar
como pendência. Toda adaptação é registrada no processo; ela não sai nas consultas nem no
acompanhamento desta versão do contrato — quem a consulta é o suporte do HubDE, pelo
X-Correlation-Id da resposta.
A recusa por 400 é reservada ao que se corrige na origem, no sistema que enviou, e que
quem estiver na tela de conferência não teria como completar:
CategoriaCampos
Identidadedocumento, tipoPessoa
Procedênciaorigem.erp, origem.codigoCedenteNoErp
Signatáriorepresentantes (pessoa jurídica), contato.email (pessoa física)
Tipo estrutural erradocadastro, endereco, contato, origem
Identificador obrigatório acima do limite também é 400 tamanho_excedido. O membro campos
nomeia cada ocorrência da requisição — não apenas a primeira; a lista completa está na
seção 10.

6. Idempotência#

Idempotency-Key é obrigatório em duas rotas, e ausente nas demais:
RotaIdempotency-Key
POST /erp/v1/sessoes-onboardingobrigatório
POST /erp/v1/duplicatasobrigatório
POST /erp/v1/duplicatas/liquidacoesnão lê o header
POST /erp/v1/sessoes-acompanhamentonão lê o header
Por que a liquidação fica de fora: ali o agregado já existe, e informar o mesmo pagamento
duas vezes é sucesso pelo próprio domínio. Nas duas primeiras a chave protege a
criação — de uma sessão e de duplicatas —, e criar duas vezes não se desfaz.
Gere a chave uma vez por envio e guarde-a. Um UUID novo a cada tentativa de repetir
anula a proteção: para o HubDE são dois envios distintos.
A repetição da mesma chave com o mesmo corpo retorna a resposta original, sem criar nada
de novo — é o que torna inócuo o duplo clique.
A repetição da mesma chave com corpo diferente é 409: são duas requisições
distintas reivindicando a mesma identidade, e retornar a resposta original descartaria
silenciosamente a correção feita. A repetição enquanto a primeira requisição está em
processamento é 409 idempotencia.em_voo, com Retry-After.
No onboarding, a comparação de corpo incide sobre documentoCedente normalizado,
tipoPessoa e o cadastro já canonicalizado e já adaptado.
Não caracteriza corpo diferenteCaracteriza corpo diferente
ordem das chavescampo acrescentado ou removido
caixa do nome das chaves do schema (chave fora do schema é comparada como veio)máscara ou caixa em valor dentro de cadastro que mude o resultado da adaptação
espaço nas pontas dos valores
propriedade com valor null
máscara do documentoCedente
Exemplo do segundo caso: cep: "89219-500" é descartado e "89219500" permanece, logo são
dois cadastros distintos.

7. Vínculo único#

Um cedente admite um único vínculo ativo em todo o HubDE, considerados todos os
clientes. Se o vínculo é de outro cliente, a requisição é recusada com
cedente_ja_vinculado. Se o vínculo é seu e o pacote de adesão ainda não foi enviado
para assinatura, o reenvio é aceito: o HubDE substitui o cadastro, responde 201 e devolve
uma url nova para a mesma jornada. Depois do envio para assinatura, o reenvio também é
cedente_ja_vinculado.
A recusa não identifica o cliente detentor do vínculo, pois isso exporia a carteira
de um cliente a outro. O membro detail descreve a pendência e deve ser
exibido a quem está na tela. Os membros escrituradora e situacao são reservados e não são
populados nesta versão do contrato.

8. Ciclo de vida dos links#

O link de onboarding é de uso único: o primeiro acesso o troca por um cookie de
sessão de 30 minutos, e a mesma url em outro navegador responde sessao.ja_utilizada.
O link de acompanhamento admite reapresentação enquanto não expirar, e o cookie dele
dura 4 horas. Os dois tokens valem 15 minutos. Link expirado antes do primeiro acesso
responde 410.

9. Convenções#

Datas e horas em UTC, ISO-8601, com offset explícito (+00:00). A fração de
segundo pode estar presente ou ausente. Utilize um parser de ISO-8601; não compare
cadeias.
CNPJ no padrão alfanumérico da Receita Federal (IN RFB 2.229/2024):
^[0-9A-Z]{12}[0-9]{2}$. Os dígitos verificadores são validados — a conformidade com o
padrão não é suficiente. CPF: 11 dígitos, também com verificação.
Máscara: as duas regras são diferentes. No documentoCedente do envelope, máscara e
letras minúsculas são aceitas e normalizadas. Em cadastro.documento a máscara é
400 formato_invalido; a caixa é normalizada para maiúsculas, como em tipoPessoa,
endereco.uf e endereco.pais. origem.erp é a única exceção: é comparado com
a caixa exata.
Envie tudo sem máscara e não dependa da normalização.
Erros seguem RFC 9457 (application/problem+json). Trate pelo membro codigo,
não pelo title.
Exceção: a repetição de uma Idempotency-Key cuja primeira
requisição foi recusada com 409 cedente_ja_vinculado retorna o mesmo status com
Content-Type: application/json e apenas os membros codigo e detail. O codigo existe
nos dois formatos, então trate sempre por ele e não condicione ao media type.
Recusa 400 e 422 não consomem a Idempotency-Key: a mesma chave, com o corpo
corrigido, é processada normalmente. Só o 409 cedente_ja_vinculado fica gravado.
Todas as respostas incluem o header X-Correlation-Id, gerado pelo Hub — um valor que
você envie é sobrescrito. Registre-o em log: é a informação solicitada pelo suporte. No
corpo, o membro instance só é preenchido nas recusas de credencial (401 e 403), e os
erros internos usam o nome traceId. Use o header.
GET /catalogo/v1/escrituradoras é a única rota pública desta especificação.

10. Códigos de erro#

Esta especificação exige o tratamento pelo codigo, e a lista completa está abaixo.
campos[].codigo é o código de cada campo dentro de cedente.precadastro_invalido, e não um
codigo de topo.
StatuscodigoCondição
400idempotency_key.nao_informadaheader ausente ou em branco
400cedente.tipo_pessoa_invalidotipoPessoa fora de FISICA e JURIDICA
400documento.nao_informadodocumentoCedente ausente
400documento.tipo_divergentecomprimento do documento não corresponde ao tipoPessoa
400cnpj.tamanho_invalido, cnpj.invalidoCNPJ com comprimento errado ou dígito verificador que não fecha
400cpf.tamanho_invalido, cpf.invalidoidem para CPF
400cedente.documento_divergentecadastro.documento diferente de documentoCedente
400cedente.precadastro_invalidovalidação do cadastro; o membro campos lista cada ocorrência
401credencial_invalidaX-Api-Key ausente, inválida, revogada, ou conta de ERP desativada
403credencial_suspensachave válida, cliente suspenso ou inexistente
409cedente_ja_vinculadovínculo ativo em qualquer cliente do HubDE
409idempotencia.conflitomesma chave, corpo diferente
409idempotencia.em_voomesma chave em processamento; Retry-After: 2
409conflito.unicidadecorrida de gravação; repita a requisição
409conflito.concorrenciaidem, por versão divergente do registro
409sessao.ja_utilizadalink de onboarding já consumido
410sessao.expiradalink expirado antes do primeiro acesso
404sessao.nao_encontradatoken inexistente, adulterado ou truncado no copiar-e-colar
422cedente.nao_encontrado_no_erprequisição sem o objeto cadastro
500erro_internofalha não prevista; o identificador vem em traceId
Das rotas de duplicata:
StatuscodigoCondição
400duplicata.filtro_situacao_invalidoa situacao do filtro não existe
400situacao.desconhecidaa situacao do filtro de GET /erp/v1/cedentes não existe
400lote_vazioduplicatas[] ou liquidacoes[] vazio
400lote_grande_demaismais de 500 duplicatas num lote
400liquidacao.lote_vazioliquidacoes[] vazio
No lote de entrada (POST /erp/v1/duplicatas) o desfecho é por item, em
duplicatas[].
Cada entrada tem posicao (base zero, a posição no array que você
enviou), referencia, situacao (aceita, ja_recebida ou recusada), duplicataId,
codigoErro, mensagemErro e campo. O contador recusadas é um número, não uma lista.
Atenção: recebidas não é a soma de aceitas e recusadas — as ja_recebida ficam
fora das duas. O corpo traz ainda protocolo — a Idempotency-Key ecoada.
No lote de liquidação (POST /erp/v1/duplicatas/liquidacoes) a forma é outra:
aceitas[] e recusadas[] são listas, e cada recusa tem indice, documentoCedente,
referencia, codigo e mensagem. É o indice que amarra a recusa à posição enviada —
percorra-o, não suponha a ordem.
Os valores de codigoErro e de recusadas[].codigo não fazem parte da lista acima: são
dezenas, por campo. O par mensagemErro/campo — e mensagem, na liquidação — é o que diz
o que corrigir. Registre o código em log e apresente a mensagem; não condicione o seu fluxo
a um valor específico.
Os valores de campos[].codigo: obrigatorio, tipo_invalido, valor_invalido,
formato_invalido, tamanho_excedido e nenhum_aproveitavel.
Fora deste formato: corpo JSON malformado responde 400 e Content-Type não suportado
responde 415, ambos sem corpo e sem codigo — são recusas do framework, anteriores ao
contrato. 499 sem corpo significa que o cliente desistiu da requisição.
Os três últimos códigos de sessao.* acontecem ao abrir o link no navegador, e não numa
chamada sua. Com Accept: text/html, o HubDE redireciona para a tela de erro em vez de
responder problem+json — e, no link de onboarding, o resgate consome o token: não o
abra programaticamente para verificação, sob pena de invalidá-lo. O link de acompanhamento
admite reapresentação até expirar, mas cada abertura rotaciona o cookie e derruba o
navegador anterior.

11. Roteiro de homologação#

A homologação ocorre no ambiente de produção, com dados de teste. Execute na ordem indicada.
1.
Credencial. GET /erp/v1/cliente responde 200 com a credencial e 401 sem ela. O
corpo contém clientId, cnpj, codigoClienteHub, erpSystem e status.
2.
Catálogo. GET /catalogo/v1/escrituradoras lista as escrituradoras publicadas, sem
credencial.
3.
Primeira sessão. POST /erp/v1/sessoes-onboarding com cadastro completo, origem
preenchida e Idempotency-Key responde 201 com a url.
4.
Header ausente. A mesma requisição sem Idempotency-Key responde
400 idempotency_key.nao_informada.
5.
Abertura da tela. A url aberta no navegador exibe o cadastro enviado, e o
recarregamento da página é preservado.
6.
Uso único. A mesma url em janela anônima não abre a tela.
7.
Idempotência. A repetição da mesma chave com o mesmo corpo retorna a resposta original.
8.
Conflito de idempotência. A mesma chave com corpo diferente responde
409 idempotencia.conflito.
9.
Cadastro parcial. Requisição sem endereço responde 201, e os campos constam como
pendência.
10.
Identificador inválido. CEP malformado responde 201, com o valor removido e o campo
pendente.
11.
Texto excedente. Razão social acima do limite responde 201 com o valor truncado, e
não pendente.
12.
Ausência de signatário. Pessoa jurídica sem representante com e-mail responde 400.
13.
origem inválida. origem.erp = "OUTRO" responde 400 cedente.precadastro_invalido,
com campos[0].campo = "origem.erp" e campos[0].codigo = "valor_invalido" — o valor
aceito é Outro, e isso confirma a sensibilidade a maiúsculas.
14.
Vínculo único. Criar sessão para cedente com vínculo ativo responde
409 cedente_ja_vinculado, e o detail é exibido na tela.
15.
Link expirado. Decorridos os 15 minutos, a abertura no navegador cai na tela de erro
(/?erro=sessao.expirada); a mesma url pedida com Accept: application/json responde
410 sessao.expirada. Lembre que abrir o link para conferir já o consome.
16.
Nova sessão. Antes da submissão para assinatura, uma nova chave substitui o cadastro
e reabre a tela.
17.
Acompanhamento. POST /erp/v1/sessoes-acompanhamento retorna o link, e o cedente da
etapa 3 consta com a etapa correta. (Não se aplica a cliente de portal do cedente — ver
a etapa 18.)
Ciclo da duplicata. Prossiga só depois que o cedente da etapa 3 estiver ativo.
18.
Situação do cedente. GET /erp/v1/cedentes?documentoCedente=… responde 200 com
uma linha, e a situacao acompanha a jornada — confirme que ela chega a ativo.
?situacao=inexistente responde 400 situacao.desconhecida.
19.
Escrituração. POST /erp/v1/duplicatas com um lote de duas duplicatas válidas e
Idempotency-Key responde 201, e a resposta ecoa as referencia enviadas.
20.
Header ausente. O mesmo lote sem Idempotency-Key responde 400.
21.
Lote parcial. Um lote com uma duplicata válida e uma inválida responde 207, e
a entrada recusada de duplicatas[] traz a posicao correta no array enviado.
22.
Lote todo inválido. Duas duplicatas inválidas respondem 207, com todas as
entradas de duplicatas[] em situacao: recusada.
23.
Cedente não ativo. Uma duplicata de cedente ainda em cadastro é aceita e fica
pendente — confirme que ela não é recusada, e que aparece na consulta do desfecho.
24.
Desfecho e IUD. GET /erp/v1/duplicatas devolve as duplicatas da etapa 19; quando a
situacao vira escriturada, o iud está preenchido. Guarde-o.
25.
Cursor. Repetir a consulta com ?atualizadoDesde= igual ao maior atualizadoEm
recebido devolve ao menos aquela linha — o corte é inclusivo, e a repetição é esperada.
26.
Liquidação. POST /erp/v1/duplicatas/liquidacoes para a duplicata da etapa 24
responde 200. A mesma chamada para uma duplicata ainda pendente é recusada.
27.
Correlação. O header X-Correlation-Id de cada resposta é registrado em log.

Troca de informações para o cadastro#

Fornecemos: a X-Api-Key da conta do ERP, emitida no cadastro do cliente no HubDE, e o
CNPJ com que o cliente foi cadastrado, para conferência via GET /erp/v1/cliente.
Precisamos receber: o CNPJ e a razão social do cliente, o identificador do sistema que
vai consumir a credencial, e em qual dos dois arranjos da seção 1 ele opera — é isso que
define quem abre o link de cadastro, e trocá-lo depois não reescreve jornada nenhuma já em
curso.
Modificado em 2026-11-20 04:12:16
Página anterior
Como começar
Próxima página
Cria a sessão de cadastro do cedente
Built with