Pix - Manual de Integração (1.1)

Integrando na Bcodex

Olá, bem-vindo à documentação técnica da Bcodex!

Nessa documentação, você vai encontrar todas as informações necessárias para integrar com as nossas APIs.

Sandbox e Produção compartilham o mesmo código, mas estão isolados um do outro, pois estão sendo executados em servidores separados e acessam bancos de dados diferentes. Mudar para Produção exige que você altere apenas a URL base e as credenciais. Os SDKs selecionam a URL base de acordo com o ambiente que você escolhe.

Postman:

Para facilitar a sua integração, disponibilizamos uma collection no Postman com todos os endPoints do produto Pix Pay.

Processo de Integração

Para se integrar na API Bcodex, você precisa passar por quatro etapas:

1. Obtenha suas credenciais de acesso

Nossas APIs possuem autenticação, utilizando SSO.

Nossos parceiros receberão por e-mail as credenciais necessárias para a autenticação no ambiente sandbox. Essas credenciais incluem o username e o password.

Com essas informações em mãos, nossos parceiros terão acesso a todas as funcionalidades disponíveis. Certifiquem-se de inserir essas credenciais de autenticação em todas as rotas relevantes.

Credenciais de Sandbox

Para acessar os endpoints em ambiente de sandbox, utilize as seguintes URL base:

Pix Pay: https://sandbox.bcodex.io/

Para obter suas credenciais, basta solicitá-las ao nosso suporte@bcodex.io informando o seu CNPJ, Nome da companhia, Nome fantasia, e a chave pix relacionada ao CNPJ informado.

Credenciais de Admin: São credenciais específicas destinadas à autenticação de um admin e à sua utilização nos endpoints designados exclusivamente para o admin.

Credenciais de Managers: São credenciais específicas destinadas à autenticação de um manager e à sua utilização nos endpoints designados exclusivamente para um manager.

No título de cada pasta de endpoints, indica qual autenticação deve ser utilizada para acessar o respectivo endpoint.

2. Integração

Nessa fase nosso cliente pode realizar seus desenvolvimento em nosso ambiente de sandbox (testes), onde é possível testar toda a comunicação com nossas apis e entender seus comportamentos.

3. Homologação

Após finalizar o desenvolvimento com as apis da Bcodex, você deverá preencher um roteiro de homologação da funcionalidade que está implementando, para que possamos validar sua integração.

4. Produção

Ao final da homologação, você receberá o nosso OK e as chaves do seu ambiente produtivo para iniciar sua operação.

Gerenciamento Manager

Autenticação

Gera o token para autenticação dos endpoints da API.

POSTGeração de token / Autenticação

https://sandbox.bcodex.io/bcdx-sso/login

Para utilizar nossos serviços, é necessário ter um token válido.

No corpo da requisição é necessário enviar os parametros conforme o exemplo.

Retorno da rota /bcdx-sso/login é um JWT, que deve ser enviado no formato Bearer em todas requisições.

HEADERS

Content-Type

application/x-www-form-urlencoded

Bodyurlencoded

username

40756355-9edd-4bc2-a23f-38fdsa780d345ba7

password

2a3cd0ab066a2755a63f90dd5633271cdsadsa

Example Request

curl

curl --location 'https://sandbox.bcodex.io/bcdx-sso/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=40756355-9edd-4bc2-a23f-38fdsa780d345ba7' \
--data-urlencode 'password=2a3cd0ab066a2755a63f90dd5633271cdsadsa'

Example Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKYnJnaE9yRFZVZDU2ZnNNOFdHQUFUOGpRN3JxbHl2clNQZDNoYkdiemdJIn0.eyJleHAiOjE3MTc0NjA0MDQsImlhdCI6MTcxNzQ1OTgwNCwianRpIjoiOTZhNzJkZDMtMjA3ZS00NDIwLTk3OTMtZjViMWZhNzBhYzJhIiwiaXNzIjoiaHR0cHM6Ly9iY29kZXgta2V5Y2xvYWstZGV2LTEyMTIwNDI1MjUudXMtZWFzdC0xLmVsYi5hbWF6b25hd3MuY29tL3JlYWxtcy9iY29kZXgiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZTNkZjVlYjEtNmI5Yi00MjdhLTk5MDYtZTQ3YjE0ODNkNTVhIiwidlvbl9zdGF0ZSI6IjhhYmEwNDE5LWY2ZTgtNDkxZS1hYjZhLTI2Mjg0OTA0M2ZhZiIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiLyoiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlBJWFBBWV9QSVhfQUxMIiwiZGVmYXVsdC1yb2xlcy1iY29kZXgiLCJjcmVhdGUtdXNlcnMiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByb2ZpbGUiOiJtYW5hZ2VyIiwibmFtZSI6InFhYmNvZGV4IiwiZ3JvdXBzIjpbIlBJWFBBWV9QSVhfQUxMIiwiZGVmYXVsdC1yb2xlcy1iY29kZXgiLCJjcmVhdGUtdXNlcnMiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiUElYUEFZX01BTkFHRVJfQUxMIl0sInByZWZlcnJlZF91c2VybmFtZSI6InFhYmNvZGV4IiwiZ2l2ZW5fbmFtZSI6InFhYmNvZGV4IiwiZW1haWwiOi0bG9vay5jb20ifQ.q8VzExx_wB8fd5u7Nezah3RdujybY6bRutUUXc8UHDiNUjbtkosK6V8t_OlyzTOzKH0HJQAzX4L91o3eyiAsh_Lpqhcws5rMs9ex1uLUB2Q0aquXzBLVICr0uYQ5fLRK5kXRfoB3XekBeXnAiLuSeDOlNw_IkjyuTP5uDWVOVUcq_D4PQCHsZ9CLv_VlBM0nr6BfAchPfBXSstYhWywsdN-UeF_pcwwBJOU6gy71BSuQnKeN9iNTvA6pVnd4qFnofGn_3BIdrnDDXRc8wHTr5H823yA1O0rkjJiHOEOjoD9wVHyQy--UFQSgeYrtMQOR9X4g",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkODVjYWI5NC0xNjYwLTRiYzktOGMxMC0wYzdiZTdiNDY5M2IifQ.eyJpYXQiOjE3MTc0NTk4MDQsImp0aSI6IjUzZjY5MmFhLTVhMDQtNDUxNS1iOTJkLTI1YzRkMDM1NDQ5NCIsImlzcyI6Imh0dHBzOi8vYmNvZGV4LWtleWNsb2FrLWRldi0xMjEyMDQyNTI1LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9yZWFsbXMvYmNvZGV4IiwiYXVkIjoiaHR0cHM6Ly9iY29kZXgta2V5Y2xvYWstZGV2LTEyMTIwNDI1MjUudXMtZWFzdC0xLmVsYi5hbWF6b25hd3MuY29tL3JlYWxtcy9iY29kZXgiLCJzdWIiOiJlM2RmNWViMS02YjliLTQyN2EtOTkwNi1lNDdiMTQ4M2Q1NWEiLCJ0eXAiOiJPZmZsaW5lIiwiYXpwIjoiYmluZC11c2VyIiwic2Vzc2lvbl9zdGF0ZSI6IjhhYmEwNDE5LWY2ZTgtNDkxZS1hYjZhLTI2Mjg0OTA0M2ZhZiIsInNjb3BlIjoicHJvZmlsZSBhZGRyZXNzIG9mZmxpbmVfYWNjZXNzIGVtYWlsIHBob25lIHVzZXJfaW5mbyBtaWNyb3Byb2ZpbGUtand0Iiwic2lkIjoiOGFiYTA0MTktZjZlOC00OTFlLWFiNmEtMjYyODQ5MDQzZmFmIn0.awGQMRHph-qWNHKZSe4jYpr33AXKo8dM6WCms1unO9Q",
  "token_type": "Bearer",
  "expires_in": 600
}

Content-Type

application/json

API Cobrança Pix

Fluxo para Criação de Cobrança e Teste de Cash-In

Para testar o Cash-in, você precisa passar por cinco etapas:

Passos:

EndPoint de Geração de Token:
- Utilize as credenciais fornecidas pelo time Bcodex para acessar o endPoint de geração de token.
- Este passo é crucial para obter a autenticação necessária para as operações subsequentes.

Endpoint Cadastrar Webhook :
- Inicie o processo configurando um webhook para receber notificações de mudanças de status.
- Certifique-se de que a URL do webhook esteja corretamente cadastrada para receber as atualizações.

Envio do Token para Geração de Cobrança:
- Com o token gerado no passo anterior, envie-o para o endPoint de geração de cobrança.
- Certifique-se de incluir todas as informações necessárias para criar a cobrança desejada.

Envio do txID para Execução do Pagamento:
- Após a geração da cobrança, obtenha o txID associado a ela.
- Envie o txID para o time Bcodex para a execução do pagamento, lembrando que, no ambiente de Sandbox, a Bcodex deve simular o pagamento da cobrança gerada.

Recebimento da Atualização do Webhook:
- Após o pagamento realizado pela Bcodex, a atualização da cobrança será enviada para a URL cadastrada no webhook.
- Certifique-se de monitorar essa URL para receber e processar as notificações de mudanças de status.

PUTGerar nova cobrança

https://sandbox.bcodex.io/cob/{{txId}}

Passos:

1. Geração de Token:

Utilize as credenciais fornecidas pelo time Bcodex.

Faça uma requisição ao endPoint de geração de token para obter a chave de autenticação necessária.

2. Envio do Token para Geração de Cobrança:

Com o token obtido no passo anterior, faça uma requisição ao endPoint de geração de cobrança.

Inclua todas as informações necessárias para criar a cobrança desejada.

Endpoint para criar uma cobrança imediata.

3. Criação de txId de forma aleatória

Crie em environments uma variavel global com o nome txId

Adicione dentro da requisição no campo "Pre Request Script" o código abaixo:

const randomUUID = require('uuid').v4();
const uuidWithoutSpecialChars = randomUUID.replace(/-/g, '');
pm.environment.set('txId', uuidWithoutSpecialChars);

Assim sempre quando gerar uma nova cobrança não precisa se preocupar em alterar o valor do txId manualmente.

OBS: Caso deseje realizar de forma manual esse processo, basta desconsiderar os passos acima e alterar o {{txId}} pelo exemplo abaixo:

formato txId : 44a279000ffa41c88caf9f835feaaa8b

Lembrando não é possível gerar um txId duplicado, havendo a necessidade de sempre alterar esse valor.

4. Atribuição do campos chave para criação de uma Cobrança:

Para que seja possível realizar a geração de uma cobrança é necessário informar o documento do estabelecimento sendo CNPJ ou o CPF referente ao cadastro:

Ex: "chave": "11111111111" ou "chave": "00000000000000" sendo aceito somente os documentos cadastrados corretamente no estabelecimento.

Campo	Tipo	Obrigatório	Descrição
calendario	Objeto	Sim	Controle de tempo da cobrança.
calendario.expiracao	integer($int32)	Sim	Tempo de vida da cobrança em segundos.
valor	Objeto	Sim	Valores monetários referentes à cobrança.
valor.original	string	Sim	Valor original da cobrança.
valor.modalidadeAlteracao	integer($int32)	Sim	Fixo 0
chave	string	Sim	Documento do Estabelecimento CNPJ/CPF
solicitacaoPagador	string	Opcional	Texto opcional a ser exibido para o pagador.
infoAdicionais	Lista	Opcional	Lista de informações adicionais para o pagador.
infoAdicionais.nome	string	Opcional	Nome do campo de informação adicional.
infoAdicionais.valor	string	Opcional	Valor do campo de informação adicional.

AUTHORIZATIONBearer Token

Token

<token>

Bodyraw (json)

json

{
    "calendario": {
        "expiracao": 3600
    },
    "valor": {
        "original": "15.00",
        "modalidadeAlteracao": 1
    },
    "chave": "Documento do Estabelecimento CNPJ/CPF",
    "solicitacaoPagador": "Descrição/Nome Estabelecimento",
    "infoAdicionais": [
    {
      "nome": "Título",
      "valor": "Descrição/Nome Estabelecimento"
    }
  ]
}

Example Request

curl

curl --location -g 'https://sandbox.bcodex.io/cob/{txid}' \
--data '{
    "calendario": {
        "expiracao": 3600
    },
    "valor": {
        "original": "15.00",
        "modalidadeAlteracao": 0
    },
    "chave": "Documento do Estabelecimento CNPJ/CPF",
    "solicitacaoPagador": "Descrição/Nome Estabelecimento",
    "infoAdicionais": [
    {
      "nome": "Título",
      "valor": "Descrição/Nome Estabelecimento"
    }
  ]
}'

200 OK

Example Response

json

{
  "calendario": {
    "criacao": "2024-04-24T12:02:17.968Z",
    "expiracao": 3600
  },
  "txid": "8e663353e341462b9607d8186230e6b7",
  "revisao": 0,
  "loc": {
    "id": "3966913956892629734",
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca2",
    "tipoCob": "COB"
  },
  "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca2",
  "status": "ATIVA",
  "valor": {
    "original": "15.00",
    "modalidadeAlteracao": 0
  },
  "chave": "6a379671-6f37-42f6-a737-453677ab4dc3",
  "solicitacaoPagador": "Descrição/Nome do Estabelecimento",
  "infoAdicionais": [
    {
      "chave": "Título",
      "valor": "Descrição/Nome do Estabelecimento"
    }
  ],
  "pixCopiaECola": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25"
}

Content-Type

application/json

GETConsultar Cobrança

https://sandbox.bcodex.io/cob/{{txId}}

1. Solicitar Token:

Utilize as credenciais fornecidas pelo time Bcodex.

Faça uma requisição ao endPoint de geração de token para obter a chave de autenticação necessária.

2. Enviar Token para Geração de Cobrança:

Utilize o token obtido no passo anterior.

Realize uma requisição ao endPoint de geração de cobrança, incluindo todas as informações relevantes para a criação da cobrança desejada.

3. Consultar Cobrança:

Após a geração da cobrança, obtenha o TXID associado a ela.

Realize uma requisição ao endPoint de consulta de cobrança, enviando o TXID da cobrança gerada.

Isso permitirá que você obtenha informações detalhadas sobre o status e outros detalhes da cobrança.

Endpoint para consultar uma cobrança através de um determinado txid.

Campo	Tipo	Obrigatório	Descrição
txid*	string	Sim	ID da transação que deve ser fornecido. Enviado no params

AUTHORIZATIONBearer Token

Token

<token>

Example Request

curl

curl --location -g 'https://sandbox.bcodex.io/cob/{{txId}}'

200 OK

Example Response

json

{
  "calendario": {
    "criacao": "2024-04-24T12:02:17.968Z",
    "expiracao": 3600
  },
  "txid": "8e663353e341462b9607d8186230e6b7",
  "revisao": 0,
  "loc": {
    "id": "3966913956892618734",
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
    "tipoCob": "COB",
    "criacao": "2024-04-24T12:02:17.968Z"
  },
  "status": "CONCLUIDA",
  "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
  "valor": {
    "original": "17.35",
    "modalidadeAlteracao": 0
  },
  "chave": "6a379671-6f37-42f6-a737-453677ab4dc3",
  "solicitacaoPagador": "Descrição",
  "pixCopiaECola": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
  "pix": [
    {
      "endToEndId": "E3030629420240424120901356765982",
      "txid": "8e663353e341462b9607d8186230e6b7",
      "horario": "2024-04-24T09:09:56.315Z",
      "valor": "17.35",
      "devolucoes": []
    }
  ],
  "pagador": {
    "banco": "xxx",
    "agencia": "x",
    "conta": "817670",
    "nome": "BANCO xxx",
    "cpfCnpj": "xxxxx",
    "tipoPessoa": "PESSOA_JURIDICA",
    "tipoConta": "CACC"
  },
  "infoAdicionais": [
    {
      "chave": "Título",
      "valor": "Descrição"
    }
  ]
}

Content-Type

application/json

PATCHAtualização da cobrança

https://sandbox.bcodex.io/cob/{{txId}}

Passos:

1. Geração de Token:

Utilize as credenciais fornecidas pelo time Bcodex.

Faça uma requisição ao endPoint de geração de token para obter a chave de autenticação necessária.

2. Envio do Token para Geração de Cobrança:

Utilize o token obtido no passo anterior.

Faça uma requisição ao endPoint de geração de cobrança, incluindo todas as informações necessárias para criar a cobrança desejada.

3. Atualização da Cobrança:

Após a geração da cobrança, obtenha o TXID associado a ela.

Faça uma requisição ao endPoint de atualização de cobrança, enviando o TXID e atualizando os campos mencionados a seguir

Exemplos de body para atualização da cobrança:

json

{
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

json

{
 
  "devedor": {
    "cpf": "12345678909",
    "nome": "Francisco da Silva"
  },
  "valor": {
    "original": "123.45"
  },
  "solicitacaoPagador": "CobranÃ§a dos serviÃ§os prestados."
}

json

{
  "valor": {
    "original": "567.89"
  },
  "solicitacaoPagador": "Informar cartÃ£o fidelidade"
}

Campo	Tipo	Descrição
status	string	Fixo: "REMOVIDA_PELO_USUARIO_RECEBEDOR". Campo utilizado para remover uma cobrança Pix

Campo	Tipo	Descrição
valor.original	string	Valor original da cobrança.
solicitacaoPagador	string	Texto opcional a ser exibido para o pagador.
devedor.cpf	string	Os campos aninhados sob o objeto devedor são opcionais e identificam o devedor, ou seja, a pessoa ou a instituição a quem a cobrança está endereçada.
devedor.nome	string	Os campos aninhados sob o objeto devedor são opcionais e identificam o devedor, ou seja, a pessoa ou a instituição a quem a cobrança está endereçada.

AUTHORIZATIONBearer Token

Token

<token>

Bodyraw (json)

json

{
  "status": "REMOVIDA_PELO_USUARIO_RECEBEDOR"
}

Example Request

curl

curl --location -g --request PATCH 'https://sandbox.bcodex.io/cob/{{txId}}' \
--header 'Content-Type: application/json' \
--data '{
    "calendario": {
        "expiracao": 3600
    },
    "valor": {
        "original": "5.00",
        "modalidadeAlteracao": 1
    },
    "chave": "Documento do Estabelecimento CNPJ/CPF",
    "solicitacaoPagador": "Descrição/Nome Estabelecimento",
        "infoAdicionais": [
    {
      "nome": "Título",
      "valor": "Descrição/Nome Estabelecimento"
    }
  ]

}'

200 OK

Example Response

json

{
  "calendario": {
    "criacao": "2024-04-24T12:22:24.344Z",
    "expiracao": 3600
  },
  "txid": "a0c6fa87206c43a98882e8d8668c7645",
  "revisao": 1,
  "loc": {
    "id": 4094234743050104300,
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca2",
    "tipoCob": "COB"
  },
  "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca2",
  "status": "ATIVA",
  "chave": "6a379671-6f37-42f6-a737-453677ab4dc3",
  "pixCopiaECola": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca2",
  "valor": {
    "original": "5.00",
    "modalidadeAlteracao": 0
  },
  "solicitacaoPagador": "Descrição/Nome Estabelecimento"
}

Content-Type

application/json