Como o roteamento funciona

Como o JD Courier decide qual motor recebe cada mensagem SPB e Pix, e o que acontece com uma mensagem que ele não consegue rotear ou entregar.

Para cada mensagem que a JD envia à sua instituição, o Courier decide apenas qual motor a recebe. Esta página explica o mapa de titularidade, as regras de roteamento de cada trilho e a retenção das mensagens que o Courier não consegue rotear ou entregar.

​

O mapa de titularidade

---

O mapa de titularidade é uma lista de chaves. Cada chave tem um motor dono. Um motor pode reivindicar as contas, os documentos de cobrador e as recorrências que detém. Um operador também pode atribuir chaves pela API de titularidade. O Courier recusa um segundo dono para uma chave com 409 JDC-0102. Para mudar o dono, o operador move a chave.

O mapa aceita oito tipos de chave:

Tipo de chave	O que identifica	Usado pelo roteamento de entrada
ACCOUNT	Uma conta, como agência e número da conta. Uma conta de pagamento não tem agência.	Sim, no SPB e no Pix
DOCUMENT	Um CPF ou um CNPJ.	Sim, no Pix Automático, para o CNPJ do cobrador
PIX_RECURRENCE_ID	Uma recorrência do Pix Automático, do lado do pagador.	Sim, no Pix Automático
PIX_RECURRENCE_ID_CHARGER	Uma recorrência do Pix Automático, do lado do cobrador.	Sim, no Pix Automático, para os cancelamentos de agendamento que a instituição do pagador pede
PIX_KEY_EMAIL	Uma chave Pix de email.	Não
PIX_KEY_PHONE	Uma chave Pix de telefone, no formato E.164.	Não
PIX_KEY_RANDOM	Uma chave Pix aleatória.	Não
PAYMENT_ID	Um identificador de pagamento.	Não

Os tipos que o roteamento de entrada não usa ficam disponíveis aos motores pela consulta de titularidade. Um motor usa a consulta para descobrir se outro motor é dono do destino de um pagamento.

O Courier normaliza cada valor de chave. Por exemplo, ele remove a pontuação de um CPF e os zeros à esquerda de uma agência. Envie o valor como você o guarda.

Cada mudança no mapa grava uma entrada no histórico de auditoria da chave, na mesma transação. A entrada registra quem fez a mudança, quando, o dono anterior e o novo dono. Uma movimentação também registra o motivo. Você pode ler o histórico de uma chave depois da remoção dela, pela consulta de auditoria por chave.

​

Roteamento no trilho SPB

---

O papel spb-consumer lê as mensagens SPB que a JD guarda para a sua instituição. O Courier guarda cada mensagem antes de decidir a rota. Depois, ele aplica estas regras, em ordem:

1. Registro de envios. Quando o número de controle (NumCtrlIF) da mensagem corresponde a um envio no registro de envios, a mensagem vai para o motor que fez o envio. Esta regra roteia as respostas às mensagens que um motor enviou.
2. Mapa de titularidade. O Courier lê a conta creditada da mensagem: agência e conta, ou a conta de pagamento. Quando o mapa tem um dono para essa conta, a mensagem vai para o dono.
3. Modo de entrega. Quando o mapa não tem dono, o Courier lê o modo de entrega declarado para o código da mensagem. Esta regra nunca se aplica aos códigos de dinheiro STR0008, STR0008R1, STR0008R2, STR0010, STR0010R1, STR0010R2, STR0005R2, STR0007R2, STR0029R2, STR0034R2, STR0037R2, STR0041R2 e STR0051R2.
4. Retenção. Quando nenhuma regra decide, o Courier retém a mensagem.

O motor deve estar habilitado. Quando a regra 1 ou a regra 2 aponta um motor desabilitado, o Courier retém a mensagem com o motivo DELIVERY_FAILED.

O Courier não empurra mensagens SPB aos motores. Cada motor pede as próprias mensagens ao Courier pela mesma interface SOAP que usa com a JD. O Courier responde com a mensagem mais antiga que espera por esse motor. Para os detalhes, veja Conectar um motor.

​

Modos de entrega

Um modo de entrega se aplica a um código de mensagem SPB. Um operador o declara com um motivo. Existem dois modos:

• ALL_ENGINES: a mensagem vai para cada motor habilitado que tem uma credencial do canal SOAP não revogada e não expirada. Quando nenhum motor tem uma, o Courier retém a mensagem com o motivo DELIVERY_FAILED.
• REFUSE: a mensagem não vai para nenhum motor. O Courier a guarda, com o estado REFUSED.

Um código sem declaração segue o padrão: um dono. O Courier recusa uma declaração para um código de dinheiro com 422 JDC-0110. Uma declaração revogada continua legível como histórico. O trilho Pix não aceita declaração.

​

Reentrega

Um operador pode servir de novo uma mensagem SPB a um dos motores para os quais a mensagem foi roteada. O Courier não pergunta de novo à JD. O próximo pedido do motor recebe a mensagem guardada, com o número de sequência original. O seu operador informa um motivo, e o Courier o registra.

​

Roteamento no trilho Pix

---

A JD envia as chamadas Pix de entrada da sua instituição ao endereço que o papel pix-ingress serve. O Courier decide o dono durante a chamada, entrega a chamada ao motor e repassa à JD a resposta do motor.

A JD faz três tipos de chamada:

• Perguntas. A JD espera uma resposta antes de continuar: validação de conta, o bloqueio do débito do Pix Automático e as validações de autorização e de agendamento. O Courier não retém uma pergunta.
• Mensagens. A JD informa um fato: cash-in, devolução e os registros, as liquidações e os eventos do Pix Automático. O Courier pode reter uma mensagem.
• Validações de conta assíncronas. A JD pergunta sobre os créditos de vários pagamentos em uma chamada e recebe um resultado para cada crédito depois. Veja Validação de conta assíncrona.

​

Qual chave roteia cada chamada

Chamada da JD	O dono é o motor dono de
Validação de conta, cash-in, devolução	A conta do recebedor
Validação de conta assíncrona	A conta do recebedor de cada crédito
Bloqueio do débito do Pix Automático	A conta no bloqueio
Débito do Pix Automático	Nenhuma chave: o motor que aceitou o bloqueio do débito. Sem um bloqueio aceito, o motor que recebeu o agendamento com o mesmo endToEndId.
Estorno do débito do Pix Automático	Nenhuma chave: o motor que recebeu o débito. Sem ele, o motor que aceitou o bloqueio do débito e, depois, o motor que recebeu o agendamento.
Registro do pagador da autorização, e o evento dele	A conta do pagador
Registro do recebedor da autorização, e o evento dele	O CNPJ do cobrador
Validação, cancelamento e eventos de status da autorização	A conta do pagador, quando o ISPB do pagador é um dos seus. O CNPJ do cobrador, quando o ISPB do pagador não é um dos seus.
Validação e registro do agendamento, e o evento de registro dele	A recorrência, do lado do pagador
Validação e registro do cancelamento do agendamento, e o evento de registro dele	A recorrência, do lado que não pediu o cancelamento (solCancelamento): o lado do cobrador ou o lado do pagador
Evento de status do agendamento	A conta do recebedor
Evento de status do cancelamento do agendamento	Nenhuma chave: o motor que recebeu o agendamento, ou o motor que recebeu o evento de status do agendamento

Os seus ISPBs são os ISPBs participantes que o operador registra nos motores.

As chamadas do Pix Automático que seguem uma etapa anterior precisam de um registro dessa etapa. O Courier registra as etapas anteriores que entrega. Para os pagamentos em andamento antes de o Courier receber o Pix, cada motor declara as próprias etapas. Veja Conectar um motor.

​

O que a JD recebe

Situação	Mensagem	Pergunta
O motor dono recebe a chamada	A resposta do motor, como veio. O Courier a guarda e responde com ela a cada reenvio da JD.	A resposta do motor, como veio.
O Courier guarda a chamada, mas não consegue roteá-la ou entregá-la	503. O Courier retém a mensagem.	—

Quando o motor responde a uma mensagem com um status 5xx, 408 ou 429, o Courier repassa essa resposta à JD e retém a mensagem. O próximo reenvio da JD chega de novo ao motor. Quando o motor responde com um status 3xx, 401 ou 403, ou não responde, a JD recebe 503 e o Courier retém a mensagem.

​

Validação de conta assíncrona

O Courier guarda a chamada da JD e responde 202 na hora, com um identificador de validação próprio. Depois, ele roteia cada crédito pela conta do recebedor dele. Cada motor dono recebe a sua parte dos créditos no caminho /v1/webhooks/validates/async do endereço Pix dele. O motor responde 202 para aceitar a sua parte.

O motor envia à JD o resultado de cada crédito pelo trânsito Pix. O Courier coloca o próprio identificador de validação no resultado e repassa o resultado à JD. Um segundo resultado diferente para o mesmo crédito recebe 409 JDC-0503. O primeiro resultado prevalece.

O próprio Courier recusa um crédito nestes casos:

• Nenhum motor é dono da conta do recebedor: AC03, na hora.
• O motor dono está desabilitado ou não tem endereço Pix: AB09, na hora.
• O Courier não consegue ler o mapa de titularidade, ou o motor dono não aceita a sua parte: o Courier tenta de novo. Quando uma tentativa falha 10 minutos ou mais depois da chegada da chamada da JD, o Courier recusa o crédito com AB09.

O Courier envia as próprias recusas à JD com a credencial da cabine SPI da sua instituição.

​

Mensagens retidas

---

Uma mensagem retida fica no banco de dados do Courier com o motivo. O Courier não a credita, não a devolve ao BACEN e não a apaga. O seu operador lista as mensagens retidas, da mais antiga para a mais nova, pela API de retidas. A lista mostra o motivo e os horários. Para o motivo ACCOUNT_UNASSIGNED, ela também mostra a chave que não tem dono, quando a mensagem tem uma. Ela não mostra o conteúdo da mensagem.

Motivo	Trilho	Significado	Verificada de novo
ACCOUNT_UNASSIGNED	SPB, Pix	O Courier leu a chave da mensagem, e nenhum motor é dono dela. No Pix, também: a etapa anterior da mensagem não tem registro.	Sim
UNRECOGNIZED_TYPE	SPB	A mensagem não tem chave que o Courier lê, e o código dela não tem modo de entrega.	Sim
OWNERSHIP_DECISION_UNAVAILABLE	Pix	O Courier não conseguiu ler os dados para a decisão. Também usado quando uma tentativa anterior enviou a mensagem a um motor que não é mais o dono.	Sim
DELIVERY_FAILED	SPB, Pix	A entrega ao motor falhou.	Sim
CLASSIFICATION_FAILED	SPB, Pix	O Courier não conseguiu classificar a mensagem.	Não

​

Como uma mensagem retida sai

O Courier verifica de novo uma mensagem retida no máximo uma vez por minuto. Quando a causa deixa de existir, a mensagem sai por conta própria. Por exemplo, um motor reivindica a conta, ou um operador atribui a conta ou habilita de novo o motor dono. No Pix, um reenvio da JD também roda a decisão de novo.

Um operador também pode pedir uma reavaliação com um motivo. O Courier registra quem pediu, quando e por quê, e verifica a mensagem primeiro. A reavaliação roda as mesmas regras de roteamento de uma mensagem nova. O operador nunca escolhe o motor. O Courier recusa uma reavaliação para o motivo CLASSIFICATION_FAILED com 422 JDC-0204.

Quando o Courier libera uma mensagem Pix, a JD não está na chamada. O Courier guarda a resposta do motor e a entrega à JD no próximo reenvio.

​

Envios à JD e o registro de envios

---

Os motores enviam as próprias mensagens SPB à JD pelo papel spb-sender. O Courier grava cada envio no registro de envios antes de o envio sair. Depois, ele envia a mensagem à JD uma vez e repassa ao motor a resposta da JD. O Courier nunca envia uma mensagem de novo por conta própria.

O registro de envios grava um destes resultados para cada envio:

Resultado	Significado
DETERMINED	A JD respondeu com um veredito.
INDETERMINATE	Nenhum veredito voltou. A mensagem possivelmente chegou à JD.
RESOLVED	Uma resposta posterior da JD resolveu um envio indeterminado.
NOT_SENT	A mensagem não saiu do Courier.

O Courier aceita cada número de controle uma vez para cada tenant. Um envio com o resultado NOT_SENT não conta. Um segundo envio do mesmo número de controle não chega à JD.

Um envio indeterminado recebe a resposta quando o motor consulta a JD sobre ele pelo Courier. Para tratar os envios indeterminados que restam, veja Operação diária.