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.
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, que lista todos os
cedentes deste cliente. Serve ao operador de um agente financiador. Num portal do
cedente, não encaminhe esse link a ninguém: ele mostra a carteira inteira.
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.
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.
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.
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.)
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.