Skip to main content
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. 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: 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: 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, 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.

​
Como o Courier lê a resposta

O Courier repassa à JD a resposta do motor. Para uma mensagem, o status decide o que acontece depois: 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, 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 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 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. 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 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, 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 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.

​
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 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 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 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. Antes de o Courier começar a receber o Pix, cada motor declara as etapas que tem 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: O Bank Transfer não devolve um TED que recebeu pelo relay. Para o lado do Bank Transfer, veja Transferências entre cores. 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, 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 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: 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.