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.

PUTCadastrar o webHook pix

https://sandbox.bcodex.io/webhook/DocumentoCNPJouCPF

Endpoint para cadastro do webhook de notificações acerca de Pix recebidos. Somente Pix associados a um txid serão notificados.

Campo	Tipo	Obrigatório	Descrição
webhookUrl*	string($uri)	Sim	URL do webhook para receber notificações (formato URI).
Documento	string	Sim	CPF ou CNPJ do EC

AUTHORIZATIONBearer Token

Token

<token>

Bodyraw (json)

json

{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}

Example Request

curl

curl --location --request PUT '' \
--data '{
  "webhookUrl": "https://pix.example.com/api/webhook/"
}'

200 OK

Example Response

json

{
  "pix": [
    {
      "txId": "08f714646220ea4d52ba7d3c5d05361c3a",
      "chave": "b2wa110c-eb6e-41b8-8c4d-ac4f354b03ea",
      "valor": "19.37",
      "horario": "2024-01-26T19:13:13.157Z",
      "pagador": {
        "nome": "xxxxx.",
        "banco": "xxxxx",
        "conta": "xxxx",
        "agencia": "1",
        "cpfCnpj": "xxxxx",
        "tipoConta": "xxxx",
        "tipoPessoa": "xxxxxx"
      },
      "devolucoes": [],
      "endToEndId": "E306355055520240126191300352240410",
      "infoPagador": "Serviço realizado.",
      "estabelecimento": "47265502176",
      "componentesValor": {
        "original": "19.37"
      }
    }
  ]
}

Content-Type

application/json

DELETECancelar o webHook pix

https://sandbox.bcodex.io/webhook/DocumentoCNPJouCPF

Endpoint para cancelamento do webhook. Não é a única forma pela qual um webhook pode ser removido.

O PSP recebedor está livre para remover unilateralmente um webhook que esteja associado a uma chave que não pertence mais a este usuário recebedor.

Campo	Tipo	Obrigatório	Descrição
Documento	string	Sim	CPF ou CNPJ do EC

AUTHORIZATIONBearer Token

Token

<token>

Example Request

curl

curl --location -g --request DELETE 'https://sandbox.bcodex.io/webhook/{chave}'

Example Response

No response body

This request doesn't return any response body

No response headers

This request doesn't return any response headers

Conciliação Admin e Gerenciamento

Guia de Utilização para Consulta de Cobranças por Admin:

Passos:

1. Geração de Autenticação do Admin:

Inicie o processo batendo no endPoint de geração de autenticação do admin.

Utilize as credenciais fornecidas pelo time Bcodex na requisição.

Obtenha o token de autenticação necessário para realizar operações como admin.

2. Consulta de Cobranças para o Admin:

Utilize o token obtido no passo anterior para enviar uma requisição ao endPoint de consulta de cobranças para o admin.

Certifique-se de incluir todos os parâmetros necessários.

Guia de Utilização para Listagem de Managers Vinculados a uma Rede por Admin:

Passos:

1. Geração de Autenticação do Admin:

Inicie o processo batendo no endPoint de geração de autenticação do admin.

Utilize as credenciais fornecidas pelo time Bcodex na requisição.

Obtenha o token de autenticação necessário para realizar operações como admin.

2. Listagem de Managers Vinculados à Rede:

Utilize o token obtido no passo anterior para enviar uma requisição ao endPoint de listagem de managers vinculados à sua rede.

Certifique-se de incluir todos os parâmetros necessários.

POSTAutenticação Admin

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

HEADERS

Content-Type

application/json

User-Agent

insomnia/2023.5.8

Bodyurlencoded

username

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

password

2a3cd0ab066a2755a63f90dd5633271cdsadsa

Example Request

curl

curl --location 'https://sandbox.bcodex.io/api/v1/admin/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'User-Agent: insomnia/2023.5.8' \
--data-urlencode 'username=40756355-9edd-4bc2-a23f-38fdsa780d345ba7' \
--data-urlencode 'password=2a3cd0ab066a2755a63f90dd5633271cdsadsa'

200 OK

Example Response

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJKYnJnaE9yRFZVZDU2ZnNNOFdHQUFUOGpRN3JxbHl2clNQZDNoYkdiemdJIn0.eyJleHAiOjE3MTc0NjA0MDQsImlhdCI6MTcxNzQ1OTgwNCwianRpIjoiOTZhNzJkZDMtMjA3ZS00NDIwLTk3OTMtZjViMWZhNzBhYzJhIiwiaXNzIjoiaHR0cHM6Ly9iY29kZXgta2V5Y2xvYWstZGV2LTEyMTIwNDI1MjUudXMtZWFzdC0xLmVsYi5hbWF6b25hd3MuY29tL3JlYWxtcy9iY29kZXgiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiZTNkZjVlYjEtNmI5Yi00MjdhLTk5MDYtZTQ35MWUtYWI2YS0yNjI4NDkwNDNmYWYiLCJ1cG4iOiJxYWJjb2RleCIsImNvbXBhbnlJZCI6ImE5MGVmZDNjLTQxMTgtNGVhZC1iNmY1LTAyMTdlM2E1NGRmYyIsImFkZHJlc3MiOnt9LCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByb2ZpbGUiOiJtYW5hZ2VyIiwibmFtZSI6InFhYmNvZGV4IiwiZ3JvdXBzIjpbIlBJWFBBWV9QSVhfQUxMIiwiZGVmYXVsdC1yb2xlcy1iY29kZXgiLCJjcmVhdGUtdXNlcnMiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiUElYUEFZX01BTkFHRVJfQUxMIl0sInByZWZlcnJlZF91c2VybmFtZSI6InFhYmNvZGV4IiwiZ2l2ZW5fbmFtZSI6InFhYmNvZGV4IiwiZW1haWwiOiJ3YWxsYWNlX3JlemVuZGVAb3V0bG9vay5jb20ifQ.q8VzExx_wB8fd5u7Nezah3RdujybY6bRutUUXc8UHDiNUjbtkosK6V8t_OlyzTOzKH0HJQAzX4L91o3eyiAsh_Lpqhcws5rMs9ex1uLUB2Q0aquXzBLVICr0uYQ5fLRK5kXRfoB3XekBeXnAiLuSeDOlNw_IkjyuTP5uDWVOVUcq_D4PQCHsZ9CLv_VlBM0nr6BfAchPfBXSstYhWywsdN-UeF_pcwwBJOU6gy71BSuQnKeN9iNTvA6pVnd4qFnofGn_3BIdrnDDXRc8wHTr5H823yA1O0rkjJiHOEOjoD9wVHyQyxpVpf2L8qR3eZ0trE7--UFQSgeYrtMQOR9X4g",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkODVjYWI5NC0xNjYwLTRiYzktOGMxMC0wYzdiZTdiNDY5M2IifQ.eyJpYXQiOjE3MTc0NTk4MDQsImp0aSI6IjUzZjY5MmFhLTVhMDQtNDUxNS1iOTJkLTI1YzRkMDM1NDQ5NCIsImlzcyI6Imh0dHBzOi8vYmNvZGV4LWtleWNsb2FrLWRldi0xMjEyMDQyNTI1LnVzLWVhc3QtMS5lbGIuYW1hem9uYXdzLmNvbS9yZWFsbXMvYmNvZGV4IiwiYXVkIjoiaHR0cHM6Ly9iY29kZXgta2V5Y2xvYWstZGV2LTEyMTIwNDI1MjUudXMtZWFzdC0xLmVsYi5hbWF6b25hd3MuY29tL3JlYWxtcy9iY29kZXgiLCJzOC00OTFlLWFiNmEtMjYyODQ5MDQzZmFmIn0.awGQMRHph-qWNHKZSe4jYpr33AXKo8dM6WCms1unO9Q",
  "token_type": "Bearer",
  "expires_in": 600
}

Content-Type

application/json

GETAdmin - Consulta de cobranças imediatas

https://sandbox.bcodex.io/api/v1/admin/charges?startDate=2023-11-01&endDate=2024-11-10&manager=&establishment=&status=&page=&limit=&liquidatedAtEndDate&liquidatedAtStartDate&paidAtEndDate&paidAtStartDate

Este endpoint disponibiliza a funcionalidade para que um administrador acesse e consulte todas as cobranças ocorridas na rede que ele supervisiona ou administra. Essa consulta abrange um registro abrangente de todas as transações financeiras realizadas na rede, fornecendo uma visão completa das operações.

AUTHORIZATIONBearer Token

HEADERS

Content-Type

application/json

PARAMS

startDate

2023-11-01

Data de início do intervalo de busca das cobranças imediatas (formato: yyyy-mm-dd).

endDate

2024-11-10

Data de término do intervalo de busca das cobranças imediatas (formato: yyyy-mm-dd).

manager

ID ou CNPJ do Manager do qual o admin deseja visualizar as cobranças (opcional).

establishment

ID ou CPF/CNPJ do EC do qual o admin deseja visualizar as cobranças (opcional).

status

Status da cobrança imediata (opcional).

page

Número da página atual na paginação dos resultados (padrão: 0).

limit

Número de itens por página na paginação (padrão: 100).

liquidatedAtEndDate

liquidatedAtStartDate

paidAtEndDate

paidAtStartDate

Example Request

curl

curl --location 'https://sandbox.bcodex.io/api/v1/admin/charges?startDate=2023-11-01&endDate=2024-11-10' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Example Response

json

{
  "pagination": {
    "items_per_page": 100,
    "current_page": 1,
    "total_pages": 1,
    "total_items": 2
  },
  "charges": [
    {
      "id": "e38e8db0-d762-4f9f-b1bf-decdea969d8c",
      "status": "LIQUIDATED",
      "created_at": "2023-11-20T21:12:51.242Z",
      "amount": "29.00",
      "paid_at": "2024-11-27T21:18:05.950Z",
      "liquidated_at": "2024-11-27T21:20:11.778Z",
      "liquidationCommission": 123,
      "info": {
        "qrCode": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
        "txId": "e53b53e3e5b1488baef5988eaa45",
        "descriptionInfo": {
          "title": "Serviço realizado."
        },
        "creditParty": {
          "key": "6a379671-6f37-42f6-a737-453677ab4dc3"
        },
        "endToEndId": "xxxx",
        "location": {
          "url": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25"
        }
      },
      "ec": {
        "id": "da0a9d36-5063-4182-b9d0-ea0b1fe6e7ce",
        "name": "bcodex",
        "document": "xxxx"
      }
    },
    {
      "id": "428d19c4-046d-4c5c-9879-ace53543c0d9",
      "status": "AWAITING_PAYMENT",
      "created_at": "2023-11-17T10:42:37.260Z",
      "amount": "450.56",
      "liquidationCommission": 123,
      "info": {
        "qrCode": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
        "descriptionInfo": {
          "title": "teste"
        },
        "creditParty": {
          "key": "6a379671-6f37-42f6-a737-453677ab4dc3"
        },
        "endToEndId": null,
        "location": {
          "url": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25"
        }
      },
      "ec": {
        "id": "xxxxx",
        "name": "bcodex",
        "document": "xxxxx"
      }
    }
  ]
}

Content-Type

application/json

GETAdmin - Listagem de Manager

https://sandbox.bcodex.io/api/v1/admin/managers/list

Este endpoint oferece a funcionalidade de consulta que permite que um administrador acesse e consulte todas as informações detalhadas dos managers que estão vinculados a ele em um sistema ou plataforma específica.

AUTHORIZATIONBearer Token

HEADERS

Content-Type

application/json

Example Request

curl

curl --location 'https://sandbox.bcodex.io/api/v1/admin/managers/list' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Example Response

json

[
    {
        "id": "5f4a52b4-21c4-4afd-ac12-6d596efdcf4b",
        "legal_info": {
            "social_name": "Bcodex",
            "fantasy_name": "Bcodex",
            "document": "xxxxxx"
        },
        "plan": {
            "id": "a2cf2758-2c0c-42ad-b183-022744c86670"
        }
    },
    {
        "id": "24a5d356-d16b-4359-ba99-0ec5e45e8215",
        "legal_info": {
            "social_name": "Exemplo Response",
            "fantasy_name": "Response",
            "document": "xxxxx"
        },
        "plan": {
            "id": "d1ba1525-0ca1-4f06-8ab0-fc28f3c77999"
        }
    }

Content-Type

application/json

POSTAdmin - Criação de um Manager

https://sandbox.bcodex.io/api/v1/manager

Este endpoint possibilita o Admin cadastrar um novo Manager de maneira prática e eficiente por meio de um endpoint.

Campo	Tipo	Descrição
legalInfo	Objeto	Informações legais da entidade.
legalInfo.socialName	string	Nome social da entidade.
legalInfo.fantasyName	string	Nome fantasia da entidade.
legalInfo.document	string	Documento identificador da entidade (CNPJ, CPF, etc.).
adminId	string	Identificador do administrador.
planId	string	Identificador do plano contratado.
billingData	Objeto	Dados de faturamento.
billingData.email	string	E-mail para faturamento.
billingData.billingDueDate	string	Data de vencimento da fatura.
billingData.billingAddress	Objeto	Endereço de faturamento.
billingData.billingAddress.cep	string	CEP do endereço de faturamento.
billingData.billingAddress.street	string	Rua do endereço de faturamento.
billingData.billingAddress.city	string	Cidade do endereço de faturamento.
billingData.billingAddress.state	string	Estado do endereço de faturamento.

HEADERS

Content-Type

application/json

Bodyraw

{
    "legalInfo": {
        "socialName": "string",
        "fantasyName": "string",
        "document": "string"
    },
     "paymentInfo": {
        "liquidationType": "PIX_KEY", // {"WALLET"}{BANK_ACCOUNT} 
        "bankAccount" :{
            "bank": "XXXX", 
            "accountType": "CCAC", // 'CCAC' | 'SLRY' | 'SVGS' | 'TRAN';
            "accountNumber": "XXXXX",
            "branch": "XXXXX" 
            },
        "accountId": "32131234123",
        "pixKey": "87754696000120",
        "document": "87754696000120"
     },
    "planId": "string",
    "billingData": {
        "email": "string",
        "billingDueDate": "string",
        "billingAddress": {
            "cep": "string",
            "street": "string",
            "city": "string",
            "state": "string"
        }
    }
}

Example Request

curl

curl --location --request GET 'https://sandbox.bcodex.io/api/v1/manager' \
--header 'Content-Type: application/json' \
--data '{
    "legalInfo": {
        "socialName": "string",
        "fantasyName": "string",
        "document": "string"
    },
     "paymentInfo": {
        "liquidationType": "PIX_KEY", // {"WALLET"}{BANK_ACCOUNT} 
        "bankAccount" :{
            "bank": "XXXX", 
            "accountType": "CCAC", // '\''CCAC'\'' | '\''SLRY'\'' | '\''SVGS'\'' | '\''TRAN'\'';
            "accountNumber": "XXXXX",
            "branch": "XXXXX" 
            },
        "accountId": "32131234123",
        "pixKey": "87754696000120",
        "document": "87754696000120"
     },
    "planId": "string",
    "billingData": {
        "email": "string",
        "billingDueDate": "string",
        "billingAddress": {
            "cep": "string",
            "street": "string",
            "city": "string",
            "state": "string"
        }
    }
}'

200 OK

Example Response

json

{
  "id": "24a5d356-d16b-4359-ba99-0ec5e45e8215",
  "legalInfo": {
    "document": "xxxx",
    "fantasyName": "Response",
    "socialName": "Exemplo Response"
  },
  "adminId": "xxxxxx",
  "billingData": {
    "billingAddress": {
      "cep": "30640000",
      "street": "Rua do Teste",
      "city": "Brasilia",
      "state": "DF"
    },
    "billingDueDate": "5",
    "email": "bcodex@bcodex.io"
  },
  "createdAt": "2024-02-07T10:29:10.535Z",
  "updatedAt": "2024-02-07T10:29:10.535Z"
}

Content-Type

application/json