helpix/README.md

P2Pix ITP oracle backend

Variáveis de ambiente necessárias no arquivo .env:

• BB_CLIENT_ID, BB_CLIENT_SECRET, e DEV_APP_KEY: Fornecidas pelo Banco do Brasil

• PRIVATE_KEY: Chave privada Ethereum (em formato hexadecimal com prefixo '0x') que vai assinar as liberações de pagamento)

Endpoints

POST /register

Registra um participante.

Chamado pelo vendedor antes de fazer deposit no smart contract.

Parametros requeridos:

• chainID
• tipoDocumento
• numeroDocumento
• numeroConta
• tipoConta
• codigoIspb

curl --request POST \
  --url http://localhost:5000/register \
  --header 'content-type: application/json' \
  --data '{
  "chainID": "1337",
  "tipoDocumento": 1,
  "numeroDocumento": 12345678900,
  "numeroConta": 1234567890123456,
  "numeroAgencia": 123,
  "tipoConta": 1,
  "codigoIspb": 0
}'

Retorna em formato JSON:

• numeroParticipante (usado no deposit do SC como pixTarget)

POST /request

Solicitação de Pagamento

Chamado pelo comprador após o lock no smart contract.

Parametros requeridos:

• amount
• pixTarget

curl -X POST http://localhost:5000/request \
-H "Content-Type: application/json" \
-d '{
    "amount": 100.00,
    "pixTarget": 123
}'

Retorna em formato JSON:

• numeroSolicitacao: usado para chamar /release depois
• textoQrCode: usado para gerar o QR PIX

GET /release/{numeroSolicitacao}

Liberação de Pagamento

Chamado pelo comprador após pagar o Pix

curl http://localhost:5000/release/123

Retorna em formato JSON:

• chainid-pixTarget
• amount: valor em wei
• pixTimestamp
• signature: assinatura ethereum compatível

mTLS

key.pem: chave privada e certificado da empresa

Descriptografar o e-CNPJ em formato PKCS#12 e converter em formato PEM (☢️ contém chave privada):

umask 077; # tirar permissão de leitura global
openssl pkcs12 -in <arquivo>.p12 -legacy -clcerts -noenc -out key.pem

bb.pem: certificado do BB

Descarregar o certificado de https://apoio.developers.bb.com.br/referency/post/646799afa2e2b90012c5ede8 e converter em formato PEM:

openssl x509 -in raiz_v3.der -inform DER -outform PEM -out bb.pem

Envio de certificado

Para criar a cadeia de certificados pra enviar pro BB usar:

openssl pkcs12 -in <arquivo>.p12 -nokeys -legacy -out cert.pem

enviar o cert.pem no formulário do portal developers como "cadeia completa".

Observações

• Para ambiente de desenvolvimento use DEBUG=true
• Em produção, o servidor usa Waitress como servidor WSGI
• Para mais informações, consulte a documentação oficial: https://developers.bb.com.br/