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 e, para o Pix, o endereço em que o motor recebe as chamadas Pix.

​
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.

​
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 Deploy.

​
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.

​
Chamadas que o motor faz ao Courier

O papel admin serve três operações para os motores. Cada motor chama a API de titularidade com a própria aplicação do Access Manager. A aplicação precisa da permissão ownership:read, e de ownership:write para reivindicar as próprias recorrências do Pix Automático e declarar as etapas de pagamento delas. O Courier responde 401 a qualquer outro chamador.

​
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 recorrência do Pix Automático

Quando o motor autoriza uma recorrência do Pix Automático, ele reivindica a recorrência. 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. Um débito e um estorno do débito vão para o motor que recebeu o bloqueio do débito. Um status de cancelamento do agendamento vai para o motor que tem o agendamento. 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 status de cancelamento ainda não chegou.
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.