> ## 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. # Conectar um motor > O que a equipe de cada motor de core bancário muda e implementa para trabalhar atrás do JD Courier: o trilho SPB, o trilho Pix, o trânsito Pix, as chamadas ao Courier e o relay entre cores. Esta página é para a equipe de cada motor que trabalha atrás do Courier: o seu core atual e o stack da Lerian. Primeiro, um operador registra o motor no Courier, pela [API de motores](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/register-an-engine.md). O registro guarda os ISPBs participantes do motor, a primeira credencial dele e os endereços em que o motor recebe as chamadas Pix e os TEDs entre cores. ## SPB: aponte o motor para o Courier *** No trilho SPB, o Courier serve a mesma interface SOAP da JD. Um motor que já fala com a JD muda o endereço e a credencial do canal. Ele mantém as mensagens e as chamadas. O papel `spb-sender` serve a interface no caminho `/soap`, em uma porta própria (padrão `8081`). Ele aceita as quatro operações da JD: | Operação | O que o Courier faz | | - | - | | `RecebeMensagem` | Entrega ao motor a mensagem SPB mais antiga que espera por ele. Quando nenhuma espera, responde com o código de fila vazia `ALS01`. O Courier não chama a JD. | | `EnviaMensagem` | Grava o envio no registro de envios, envia a mensagem à JD uma vez e repassa a resposta da JD. | | `ConsultaNumCtrlIF` | Repassa a consulta à JD, para os números de controle dos envios que este motor fez pelo Courier. | | `ConsultaMensagem` | Repassa a consulta à JD, para os números de sequência das mensagens deste motor. | Cada motor se autentica no endereço SOAP do Courier com a própria credencial de canal, não com a sua credencial JD. Um operador emite a credencial pela API do Courier. A resposta mostra a senha uma vez. Guarde-a nesse momento. Quando você emite uma nova credencial para o mesmo motor, a anterior continua funcionando durante uma janela de sobreposição (24 horas por padrão) e depois para. Um operador pode revogar uma credencial a qualquer momento. O Courier repassa cada envio à JD com a sua credencial JD. Uma autenticação recusada recebe 401 sem corpo. ### Antes de o motor mudar o endereço 1. Zere o backlog de conciliação do motor com a JD. O Courier responde a uma consulta apenas para os envios e as mensagens que passaram por ele. Uma consulta sobre um envio anterior recebe `503`. 2. Peça ao operador para emitir a credencial do canal do motor. 3. Mude o endereço e a credencial JD do motor para os valores do Courier. ### O que o motor recebe Uma mensagem reentregue mantém o número de sequência original (`NumCabSeq`). O motor deve aceitar um número de sequência repetido como uma repetição, não como uma mensagem nova. O Courier dá estas respostas a `EnviaMensagem`: | Resposta | Significado | | - | - | | A resposta da JD, como veio | A JD respondeu. | | A resposta da JD com o header `X-Send-Outcome: indeterminate` | A JD falhou ou respondeu sem um veredito. A mensagem possivelmente chegou à JD. | | `503` com `X-Send-Outcome: indeterminate` e `X-Control-Id` | A mensagem saiu e nenhuma resposta voltou. Ela possivelmente chegou à JD. | | `503` com `X-Send-Outcome: duplicate` | O número de controle já tem um envio. O Courier não enviou a mensagem. | | `503` sem `X-Send-Outcome` | A mensagem não chegou à JD. | Depois de um envio indeterminado, consulte o número de controle com `ConsultaNumCtrlIF`. Uma resposta final da JD resolve o envio no registro. Não envie a mensagem de novo com o mesmo número de controle: o Courier a recusa. Quando cada envio anterior do número de controle tem o resultado `NOT_SENT`, o Courier responde à consulta com o código JD `ALN01`, e ele não repassa a consulta. ## Pix: receba as chamadas da JD *** No trilho Pix, o Courier entrega cada chamada de entrada ao endereço Pix do motor dono. O motor serve os mesmos caminhos que a JD chama, para a validação de conta, o cash-in, a devolução e as chamadas do Pix Automático. Para uma [validação de conta assíncrona](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-routing.md#asynchronous-account-validation), o motor recebe a sua parte dos créditos em `/v1/webhooks/validates/async`. ### Como o Courier chama o motor * O Courier anexa o caminho da chamada da JD ao endereço Pix do motor. Ele usa o mesmo método. * O corpo é o corpo que a JD enviou, byte a byte. * O Courier repassa estes headers quando a JD os envia: `Chave-Idempotencia`, `X-DataHoraEvento`, `X-NomeEvento` e `Content-Type`. * O Courier espera a resposta por até 60 segundos. Ele lê até 1 MiB da resposta. * O Courier não segue redirecionamentos. Para entregar as mensagens Pix, o Courier chama o endereço Pix que você registra para cada motor. Registre uma credencial para cada motor: então, o Courier envia um token do Access Manager em cada chamada. Sem uma credencial, o Courier chama o motor sem autenticação. Em produção, use um endereço https. Registrar um endereço Pix exige a permissão `pix-delivery:write`. O client ID e o secret do motor ficam no AWS Secrets Manager. Veja [Credenciais dos motores](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials). ### Como o Courier lê a resposta O Courier repassa à JD a resposta do motor. Para uma mensagem, o status decide o que acontece depois: | Status do motor | Resultado | | - | - | | `5xx`, `408`, `429` | O Courier repassa a resposta à JD e retém a mensagem. O próximo reenvio da JD chega de novo ao motor. | | `3xx`, `401`, `403` ou nenhuma resposta | A JD recebe `503`, e o Courier retém a mensagem. | | Qualquer outro status, por exemplo `200`, `400` ou `422` | A mensagem é entregue. O Courier guarda a resposta e a entrega à JD a cada reenvio. | Um status da última linha é final. Para a JD enviar a mensagem de novo, responda com um status da primeira linha. O motor pode receber a mesma mensagem mais de uma vez. Por exemplo, o Courier chama o motor de novo depois de um timeout. Use os identificadores que a JD envia, como `Chave-Idempotencia`, para reconhecer uma repetição. ## Pix: envie chamadas à JD pelo Courier *** Quando você liga o [trânsito Pix](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-deployment.md#pix-transit), um motor envia as chamadas Pix dele à JD pelo Courier, nos caminhos JDPI que ele usa com a JD. O Courier chama a JD com a credencial da cabine SPI da sua instituição. 1. Peça ao operador para [emitir a credencial do trânsito Pix](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/issue-the-engines-pix-transit-credential.md) do motor. A resposta mostra o secret uma vez. Guarde-o nesse momento. 2. Mude o endereço JDPI do motor para o endereço do trânsito. 3. O motor pede o token no caminho de token JDPI do trânsito, com o client ID e o secret dessa credencial. O próprio Courier responde ao pedido de token. Quando você emite uma nova credencial do trânsito Pix para o mesmo motor, a anterior continua funcionando durante a janela de sobreposição e depois para. Um operador pode [revogar uma credencial](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/revoke-one-of-the-engines-pix-transit-credentials.md) a qualquer momento, e os tokens dela param na hora. Fora do resultado da validação de conta, o Courier escreve por conta própria apenas estas respostas: o token, um `401` sem corpo para uma credencial recusada, um `404` sem corpo para um caminho fora dos caminhos JDPI e um `503` com `X-Send-Outcome: not-sent`. Esse `503` significa que nada chegou à JD, e o motor pode liberar a retenção. Todas as outras respostas, inclusive um `503` da JD, voltam como a JD as escreveu. Quando a requisição pode ter chegado à JD e a resposta da JD se perde, o Courier fecha a conexão sem resposta. Trate esse resultado como desconhecido e concilie-o antes de liberar qualquer coisa. Nenhum proxy entre o motor e o JD Courier pode repetir um `503`. No resultado da validação de conta, o Courier também pode responder `409 JDC-0503`: o crédito já tem um resultado diferente, e o primeiro prevalece. Um `503 JDC-9001` nesse caminho significa que a JD não deu veredito ou que o Courier não conseguiu repassar o resultado: envie o mesmo resultado de novo com o mesmo `Chave-Idempotencia`. ## Chamadas que o motor faz ao Courier *** O papel `admin` serve as operações que os motores chamam: a consulta de titularidade, as reivindicações, as declarações de etapa e o [relay entre cores](#cross-core-relay). Cada motor chama essas operações com uma aplicação do Access Manager que o operador vincula ao motor. Um motor pode ter várias aplicações, uma para cada produto que chama o Courier. Um exemplo é o plugin Pix e o plugin TED do stack da Lerian. O operador registra a primeira aplicação com o motor e [vincula](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/bind-one-more-credential-to-the-engine.md) cada uma das outras. Uma aplicação pertence a um motor apenas. Ela precisa da permissão `ownership:read` para a consulta, de `ownership:write` para as reivindicações e as declarações de etapa, e de `cross-core:send` para o relay entre cores. O Courier responde `401` a qualquer outro chamador. Quando o motor é o [Pix via JD](https://docs.lerian.studio/pt/interfaces/pix-jd/direct-pix-via-jd.md), o worker dele reivindica no Courier as recorrências dele, do lado do pagador ou do cobrador, e o CNPJ de cada cobrador que ele atende. Antes de o Courier começar a receber o Pix, um operador chama a [rota de propriedade do Courier](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s.md) dele (`POST /v1/pix-automatico/courier-ownership`). A rota reivindica as recorrências que já existem e declara as etapas dos pagamentos em andamento. Veja [Reivindicações no Courier](https://docs.lerian.studio/pt/interfaces/pix-jd/pix-jd-environment-variables.md#claims-on-the-courier). ### Consulta de titularidade Antes de o motor liquidar um pagamento dentro da sua instituição, ele deve saber qual motor é dono do destino. Chame a [consulta de titularidade](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key.md) com a chave como você a guarda. A resposta diz se a chave tem um dono, e se esse dono é o motor que fez a chamada. A resposta é definitiva: * `200` com `resolved: true` aponta o dono. * `200` com `resolved: false` significa que nenhum motor da sua instituição é dono da chave. * `422` significa que a chave não é válida. * Trate qualquer outro status como uma recusa: falhe o pagamento e não o liquide dentro da sua instituição. ### Reivindicação de contas e documentos [Reivindique](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/claim-accounts-charger-documents-and-recurrence-charger-sides-for-the-calling-engine.md) cada conta que o motor abre, quando ele a abre. Antes da virada, reivindique da mesma forma as contas que o motor já tem, até 1000 chaves em cada chamada. A mesma chamada reivindica o CNPJ de cada cobrador do Pix Automático que o motor atende (`DOCUMENT`) e o lado do cobrador de cada recorrência (`PIX_RECURRENCE_ID_CHARGER`). * Reivindique uma conta de pagamento sem agência. Uma conta de pagamento reivindicada com agência é uma chave que o roteamento nunca lê. * A resposta dá um resultado para cada chave, na ordem da requisição: `CLAIMED`, `ALREADY_OWNED`, `HELD_ELSEWHERE` ou `INVALID`. Informe cada `HELD_ELSEWHERE` a um operador: apenas um operador move uma chave. * Depois de um `503` ou de uma resposta perdida, envie a mesma chamada de novo. A reivindicação é idempotente. ### Reivindicação de recorrência do Pix Automático Quando o motor autoriza uma recorrência do Pix Automático, ele [reivindica a recorrência](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/claim-a-pix-automatico-recurrence-for-the-calling-engine.md) do lado do pagador. Então, o Courier roteia ao motor as chamadas de agendamento dessa recorrência. A reivindicação é idempotente. Uma recorrência que outro motor tem recebe `409 JDC-0102`. Apenas um operador pode movê-la. Antes de o Courier começar a receber o Pix, cada motor reivindica as recorrências que já existem. Uma mensagem de agendamento para uma recorrência sem dono fica retida até a reivindicação chegar. Uma validação de agendamento para essa recorrência recebe `503`. ### Declaração de etapa do Pix Automático Algumas chamadas do Pix Automático seguem uma etapa anterior do mesmo pagamento. Veja [Qual chave roteia cada chamada](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-routing.md#which-key-routes-each-call). Antes de o Courier começar a receber o Pix, cada motor [declara as etapas que tem](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/declare-an-earlier-leg-of-a-pix-automatico-payment-the-calling-engine-holds.md) para os pagamentos em andamento: * `block`: cada bloqueio do débito que o motor aceitou, quando o débito ou o estorno dele ainda não chegou. * `schedule`: cada agendamento cujo débito, estorno ou status de cancelamento ainda não chegou. Sem um bloqueio aceito, o débito e o estorno dele seguem o agendamento. Uma chamada que chega antes de a etapa ser declarada fica retida. O Courier a libera depois da declaração. Uma declaração que conflita com o registro do Courier recebe `409 JDC-0116`. Pare e informe a um operador. ## Relay entre cores *** Dois motores da sua instituição podem compartilhar um ISPB. Um pagamento de uma conta de um motor para uma conta do outro motor não vai ao STR nem ao SPI. O motor pagador o envia ao motor dono pelo Courier. O Courier repassa quatro tipos de pagamento: | Pagamento | O motor pagador chama | O motor dono o recebe em | | - | - | - | | Crédito de TED | [`POST /v1/cross-core/ted/credits`](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/relay-a-cross-core-ted-credit) | `/v1/cross-core/ted/credits` do endereço TED dele | | Devolução de TED | [`POST /v1/cross-core/ted/returns`](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/relay-a-cross-core-ted-return) | `/v1/cross-core/ted/returns` do endereço TED dele | | Cash-in de Pix | [`POST /v1/cross-core/pix/cash-ins`](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/relay-a-cross-core-pix-cash-in) | `/v1/cross-core/pix/cash-ins` do endereço Pix dele | | Devolução de Pix | [`POST /v1/cross-core/pix/refunds`](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/relay-a-cross-core-pix-refund) | `/v1/cross-core/pix/refunds` do endereço Pix dele | O Bank Transfer não devolve um TED que recebeu pelo relay. Para o lado do Bank Transfer, veja [Transferências entre cores](https://docs.lerian.studio/pt/interfaces/ted-jd/ted-cross-core.md). Cada motor segue o contrato abaixo, inclusive o outro core da sua instituição. ### Receber um pagamento entre cores 1. Peça ao operador para registrar o endereço TED (`tedDelivery`) e o endereço Pix (`pixDelivery`) do motor. Defini-los exige as permissões `ted-delivery:write` e `pix-delivery:write`. 2. Sirva os caminhos da tabela. O Courier envia o corpo do motor pagador byte a byte. Ele também envia `Content-Type`, `Chave-Idempotencia` quando o motor pagador o envia, e `X-Courier-Origin-Engine` com o ID do motor pagador. Quando o endereço tem uma [credencial](https://docs.lerian.studio/pt/interfaces/jd-courier/jd-courier-deployment.md#engine-credentials), o Courier envia um token do Access Manager. 3. Responda com um status `2xx` quando você creditar o recebedor. O Courier repassa a sua resposta ao motor pagador como você a escreveu. O Courier faz uma tentativa e espera até 15 segundos. O Courier trata um redirecionamento, um `401` e um `403` do seu endereço como uma chamada que você não aceitou. O motor pagador envia os mesmos bytes de novo enquanto o resultado dele é desconhecido, então credite cada pagamento uma vez. ### Enviar um pagamento entre cores 1. Chame a [consulta de titularidade](https://docs.lerian.studio/pt/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key.md) para a conta do recebedor. Envie o pagamento pelo relay apenas quando outro motor é dono da conta. 2. Chame o caminho do relay com uma aplicação do motor que tem a permissão `cross-core:send`. Envie o header `X-Courier-Expected-Owner` com o ID do motor que a consulta retornou. 3. Coloque a conta do recebedor no corpo. No TED, o Courier lê `payee.branch`, `payee.account` e `payee.accountType` (`PG` para uma conta de pagamento, sem agência). No Pix, ele lê `recebedor.nrAgencia`, `recebedor.nrConta` e `recebedor.tpConta` (`3` para uma conta de pagamento, sem agência). O Courier repassa a chamada apenas quando o mapa aponta o motor em `X-Courier-Expected-Owner`. Leia a resposta dele assim: | Resposta | Significado | | - | - | | O status e o corpo do motor dono, sem `X-Send-Outcome` | A chamada chegou ao motor dono. Um status `2xx` significa que ele creditou o recebedor. | | `X-Send-Outcome: not-sent` | Nada chegou a um recebedor. O código dá a causa, por exemplo: `409 JDC-0118`, nenhum motor é dono da conta; `409 JDC-0119`, o dono não é o motor em `X-Courier-Expected-Owner`; `409 JDC-0121`, a conta é sua; `503 JDC-0120`, o motor dono está desabilitado, não tem endereço para o trilho ou não aceitou a chamada. | | `401` | O Courier recusou a sua credencial. Nada foi enviado. | | Nenhuma resposta: o Courier fecha a conexão | A chamada pode ter chegado ao motor dono, e a resposta dele não voltou em 15 segundos. O resultado é desconhecido. Envie os mesmos bytes de novo. | Trate `X-Send-Outcome: not-sent` como não enviado. Ele vale apenas para esta chamada. Quando uma tentativa anterior do mesmo pagamento teve um resultado desconhecido, mantenha a retenção: envie os mesmos bytes de novo, ou pare para um operador depois de `409 JDC-0119`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.