> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/claim-accounts-charger-documents-and-recurrence-charger-sides-for-the-calling-engine.md) as contas, os documentos de cobrador e as recorrências que detém. Um operador também pode atribuir chaves pela [API de titularidade](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/assign-a-key-to-an-engine.md). O Courier recusa um segundo dono para uma chave com `409 JDC-0102`. Para mudar o dono, o operador [move a chave](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/move-a-key-to-another-engine.md). 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key.md). 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/ownership-history-for-one-key-addressed-by-the-key.md). ## 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](#sends-to-jd-and-the-send-journal), 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](#delivery-modes) 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](#retained-messages) 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](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-engine-integration.md). ### Modos de entrega Um modo de entrega se aplica a um código de mensagem SPB. Um operador [o declara](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/declare-the-delivery-mode-for-one-message-code.md) 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/reopen-the-delivery-of-a-message-to-an-engine.md) 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](#asynchronous-account-validation). ### 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](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-engine-integration.md). ### 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](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-engine-integration.md#pix-send-calls-to-jd-through-the-courier). 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/list-retained-messages.md). 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](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again.md) 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](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-operations.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.