Codec das mensagens ISO 20022 do catálogo do SPI (Pix).

encode/2 e decode/1 são genéricos: despacham pelo tipo do modelo na ida e pelo namespace do XML na volta, então você não precisa saber de antemão qual mensagem está em jogo. O schema vem dos XSDs publicados pelo Banco Central, que não são redistribuídos aqui (ver mix catalog.gen).

envelope = %Isox.Envelope{
  header: %Isox.AppHdr{...},
  message: %Isox.Pacs008{...}
}

{:ok, xml} = Isox.encode(envelope, :v1_16)
{:ok, %Isox.Envelope{message: %Isox.Pacs008{}}, :v1_16} = Isox.decode(xml)

encode/2 recebe um Isox.Envelope, que é o par cabeçalho e mensagem, mais a versão do schema, e devolve o XML pronto e já validado. decode/1 faz o caminho inverso e devolve os dois de volta dentro de um envelope.

Cada mensagem também tem seu módulo de baixo nível, com a mesma forma de API mas sem o despacho automático. Serve para quando você já sabe o que está manipulando:

{:ok, xml} = Isox.Pacs008.encode(mensagem, cabecalho, :v1_16)
{:ok, mensagem, :v1_16} = Isox.Pacs008.decode(xml)

O que cada campo quer dizer

A pergunta que mais aparece integrando com o SPI é o que é um campo. O Isox.Dictionary responde, sem sair do editor:

iex> {:ok, entrada} = Isox.Dictionary.field(Isox.Pacs008, :dbtr_acct_id)
iex> entrada.name_br
"contaUsuarioPagador"

explain/2 mostra o campo inteiro, com caminho no XML, regra de preenchimento e valores aceitos. search/1 procura por qualquer termo em todas as mensagens. A documentação de cada mensagem traz a mesma informação em tabela.

Assinatura digital

sign/4, verify/2 e generate_test_certificate/0 cobrem o dia a dia: assinar o que sua aplicação envia, verificar o que ela recebe e gerar certificado descartável para testar.

Por baixo, quem faz isso é Isox.Xmldsig, um módulo à parte que não conhece estrutura de mensagem nenhuma. Para esta camada de codec, <Sgntr> é sempre opaco. Vá direto lá só se precisar de controle mais fino, como um perfil com outro número de referências.

# Os dois lados usam chaves opostas. Para assinar o que você manda,
# é a sua chave privada com o seu certificado. Para verificar o que
# você recebe, é o certificado público de quem assinou. Nenhum dos
# lados precisa da chave privada do outro. Ver a seção de
# certificados no README.
signature_xml = Isox.sign(app_hdr_xml, document_xml, minha_chave_privada_der, meu_certificado_der)
:ok = Isox.verify(envelope_recebido_xml, certificado_de_quem_enviou_der)