> ## 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. O Courier decide uma coisa para cada mensagem que a JD envia à sua instituição: 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 operador cria e muda o mapa pela [API de titularidade](/pt/reference/interfaces/jd-courier/assign-a-key-to-an-engine). O Courier recusa um segundo dono para uma chave com `409 JDC-0102`. Para mudar o dono, o operador [move a chave](/pt/reference/interfaces/jd-courier/move-a-key-to-another-engine). O mapa aceita sete 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. | Sim, no Pix Automático | | `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](/pt/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key). 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](/pt/reference/interfaces/jd-courier/ownership-history-for-one-key-addressed-by-the-key). ## 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` e `STR0010R2`. 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](/pt/interfaces/jd-courier/jd-courier-engine-integration).

Modos de entrega

Um modo de entrega se aplica a um código de mensagem SPB. Um operador [o declara](/pt/reference/interfaces/jd-courier/declare-the-delivery-mode-for-one-message-code) com um motivo. Existem dois modos: * `ALL_ENGINES`: a mensagem vai para cada motor habilitado. * `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](/pt/reference/interfaces/jd-courier/reopen-the-delivery-of-a-message-to-an-engine) 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. ### Bypass Um bypass é o estado em que um motor se conecta de novo à JD diretamente, fora do Courier. Um operador declara um bypass no trilho SPB com o motor e um motivo. Enquanto um bypass está ativo, o Courier não lê da JD nesse trilho. Ele também não roteia nem verifica de novo as mensagens SPB. Um ciclo de conciliação que roda durante um bypass lista as garantias suspensas. No máximo um motor pode estar em bypass em um trilho. O trilho Pix não tem bypass. ## 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 dois 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. ### 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 | | Bloqueio do débito do Pix Automático | A conta no bloqueio | | Débito e estorno do débito do Pix Automático | Nenhuma chave: a chamada vai para o motor que recebeu o bloqueio do débito | | 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, registro e cancelamento do agendamento, e os eventos de registro deles | A recorrência | | Evento de status do agendamento | A conta do recebedor | | Evento de status do cancelamento do agendamento | Nenhuma chave: a chamada vai para o motor que tem o 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](/pt/interfaces/jd-courier/jd-courier-engine-integration). ### 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.

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](/pt/reference/interfaces/jd-courier/list-retained-messages). A lista mostra o motivo e os horários. 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 cada mensagem retida com uma causa de roteamento ou de entrega, no máximo uma vez por minuto. Quando a causa deixa de existir, a mensagem sai por conta própria. Por exemplo, 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](/pt/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again) 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` | A mensagem saiu, e nenhum veredito voltou. Ela 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](/pt/interfaces/jd-courier/jd-courier-operations). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.