Referências de API
Start typing to search…

Integração Pix em Lote

Objetivo

Facilitar operações de alto volume de transações Pix, de forma escalável e auto-gerenciável para evitar intervenções manuais em caso de instabilidades na Atar, Parceiro liquidante ou arranjo Pix.

Demanda

A demanda consiste em criar uma API e interface para criação, execução, gerenciamento e acompanhamento de lotes Pix. O cliente deve conseguir consumir a funcionalidade via uma interface WEB, ou via integração de API.

Procedimento Existente

Atualmente o gerenciamento de lote fica a cargo do cliente que está integrando, onde ele executa cada operação individualmente. Em lotes com o volume alto de transações, podem existir gargalos e inconsistências na Atar e no Liquidante, gerando erros inesperados e transações presas, afetando a integridade do sistema.

Requisitos

Como requisito será necessário criar:

  • Um novo micro serviço para operações de Pix em lote, onde o usuário poderá criar lotes, executar lote, acompanhar execução do lote e consultar comprovantes;
  • Uma interface WEB que permita o usuário criar lotes manualmente, executar lote, acompanhar execução do lote e baixar comprovantes.

Todo o processamento do lote deverá ocorrer de forma assíncrona, utilizando a chave de idempotência para reprocessar a transação em caso de falha de comunicação ou instabilidade.

Em caso de chargeback da transação por instabilidade no arranjo, a transação deve ser reprocessada.

Em caso de transações que não sofreram atualização por parte do Liquidante após algum tempo, o sistema deve buscar um estímulo, ou caso necessário, enviar alertas de transações pendentes para o suporte.

Instruções

1.Criação

1.1 Criação do lote(Batch):

Para iniciar o processo de envio do lote, é necessário a criação do mesmo, no exemplo abaixo, detalhamos o que ocorre em cada etapa da requisição.

Endpoint 

- POST /pix/batch

Campos de entrada: 

{
  "name": "string" # nome do lote
}

Exemplo cURL: 

curl --location --request POST '{URI}/pix/batch' \
--header 'Atar-ApiKey: 00be0083-8c8d-4d09-9f8f-***********' \ # Api key de acesso
--header 'Authorization: Bearer eyJhbGciOiJIUzI1**********' \ # token
--header 'Content-Type: application/json' \
--data-raw '{ 
    "name": "Brenno Test" 
}' # payload

Exemplo de resposta: 

{
    "status": "pending", # status do lote
    "name": "Brenno Test", # nome do lote
    "quantityItems": 0, # quantidade de itens dentro do lote
    "timestamp": 1662650197, # timestamp da criação do lote
    "type": "pix", # tipo de transação
    "id": "ag5zfndlYXJhdGFyLWRldnIdCxIQVHJhbnNhY3Rpb25CYXRjaBiAgMC87_29CgyiAQNwYXk" # identificador do lote
}

1.2 Inserindo Itens no lote(batch):

Para inserir itens no lote, o primeiro passo é consultar a chave pix da qual deseja inserir no item, utiliza-se o endpoint GET /pix/keys/{key}, obtendo os detalhes da chave, poderá inserir no campo To do item, a seguir o exemplo de detalhes retornados.

{
    "accountType": "checkingAccount", # Tipo da conta 
    "branch": "37**", # Agencia 
    "key": "5511*********", # Chave pix informada
    "accountNumber": "12345678",# Numero da conta
    "institutionName": "Atar", # Nome da instituicao da conta
    "document": "12345678912", # Documento do portador da chave
    "type": "phone",# Tipo de chave
    "institution": "********", # Indentificador da instituicao da conta
    "name": "Brenno Camilo Maia" # Nome do portador da chave
}

Insere itens no lote:

Endpoint
Deve ser informado o id do lote e as informações do pagamento e pagador;

-POST /pix/batch/{batchId}/items

Exemplo de cURL: 

curl --location --request POST '{URI}/pix/batch/{BatchID}/items' \
--header 'Atar-ApiKey: 00be0083-8c8d-**********' \
--header 'Authorization: Bearer eyJhbGc**********' \
--header 'Content-Type: application/json' \
--data-raw '[
  {
    "amount": 10, # valor
    "identifier": "02fb7933-6996-44cc-aaef-2b7683a130f6", # identificador
    "description": "Pagamento", # descrição do item
    "to": {
        "accountType": "checkingAccount", # dados que serão utilizados para envio do pix, é possível pegar no -GET /pix/keys/{key}
        "branch": "string",
        "key": "string",
        "accountNumber": "string",
        "institutionName": "string",
        "document": "string",
        "type": "string",
        "institution": "string",
        "name": "string"
    }
  }
]'

Exemplo de resposta: 

{
    "data": [
        {
            "itemId": "ag5zfndlYXJhdGFyLWRldnIhCxIUVHJhbnNhY3Rpb25CYXRjaEl0ZW0YgIDAgunWwwoMogEDcGF5", # id do item
            "status": "waiting", # status do item
            "description": "Pagamento", # descrição
            "to": { # dados que serão utilizados para a transação.
                "accountType": "checkingAccount", # tipo de conta
                "accountNumber": "string", # numero da conta
                "institutionName": "string", # instituição
                "key": "string", # key do pix
                "branch": "string", # agencia
                "document": "string", # documento
                "type": "string", # tipo da chave pix
                "institution": "string", # numero instituição
                "name": "string" nome
            },
            "amount": 10, # valor
            "identifier": "02fb7933-6996-44cc-aaef-2b7683a130f6" # identificador
        }
    ]
}

2. Edição

2.1 Edição do lote:

Para editar um lote estão disponíveis as seguintes ações, deletar um item do lote, seja um item indesejado ou para alterar um dado do item. A rota utilizada não permite o método PUT, então é necessário deletar um ou mais itens e adiciona-los novamente. Também é possível deletar um lote cadastro se o mesmo ainda em estado de aguardando o processamento(pending).

Endpoint
Consultando os lotes já cadastrados, é possível identificar o lote desejado para edição, conforme o detalhamento descrito em Visualização(logo abaixo).

Deve ser informado o BatchId e o ItemId e as informações do pagamento e pagador;

- DELETE /pix/batch/{batchId}/items/{itemId}

Exemplo de cURL: 

curl --location --request DELETE 'https://{URI}/pix/batch/{batchId}/items/{itemId}' \
--header 'Atar-ApiKey: 00be0083-8c8d***********' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI***************'

Exemplo de resposta:
202 Accepted

2.2 Remover um lote

Deve ser informado o BatchId para remoção do mesmo.

Endpoint: 

- DELETE /pix/batch/{BatchId}

Exemplo de cURL: 

curl --location --request DELETE 'https://{URI}/pix/batch/{BatchId}' \
--header 'Atar-ApiKey: 00be0083-8c8**********' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1*********'

Exemplo de resposta:
202 Accepted

3. Execução

3.1 Start do processo

Neste momento inicia o processo de envio dos lotes para pagamento

Endpoint
Deve ser informado o id do lote e as informações do pagamento e pagador;

-POST /pix/batch/{BatchId/start-process

Exemplo de cURL: 

curl --location --request POST 'https://{URI}/pix/batch/{BatchID}/start-process' \
--header 'Atar-ApiKey: 00be0083-8c*******' \
--header 'Authorization: Bearer eyJhbGciOiJI*******'

Exemplo de resposta: 

{
    "status": "processing", # status
    "timestamp": 1662650197, # timestamp
    "id": "ag5zfndlYXJhdGFyLWRl", # identificador
    "name": "Brenno Test" # nome do lote
}

4. Visualização

Consultar os dados de um Batch ou itens, também é possível acompanhar o processamento do lote.

4.1 Consultando os lotes cadastrados;

Neste momento é possível exibir todos os lotes criados.

Endpoint: 

- GET /pix/batch

Exemplo cURL: 

curl --location --request GET '{URI}/pix/batch' \
--header 'Atar-ApiKey: 00be0083-8c8d-4d09-9f8f-***********' \ # Api key de acesso
--header 'Authorization: Bearer eyJhbGciOiJIUzI1**********' \ token
--header 'Content-Type: application/json'

Exemplo de resposta:
A estrutura de retorno é a mesma de quando o lote cadastrado, contendo os mesmos campos: status, name, quantityItems, timestamp, type, id, exceto o cursor, falarei sobre ele a seguir;

{
    "cursor": null,
    "data": [
        {
            "status": "pending", 
            "name": "Brenno Test",
            "quantityItems": 0,
            "timestamp": 1662650197,
            "type": "pix",
            "id": "ag5zfndlYXJhdGFyLWRldnIdCxIQVHJhbnNhY3Rpb25CYXRjaBiAgMC87_29CgyiAQNwYXk"
        },
        {
            "status": "pending",
            "name": "Felipe",
            "quantityItems": 4,
            "timestamp": 1661526634,
            "type": "pix",
            "id": "ag5zfndlYXJhdGFyLWRldnIdCxIQVHJhbnNhY3Rpb25CYXRjaBiAgMCsxfyUCQyiAQNwYXk"# s"
        }

Pontos de atenção:

Cursor: este campo faz o papel de uma paginação, quando este campo é diferente de null, isso significa que existe mais informações em uma outra pagina, para ter acesso a mesma deve executar o endpoint passando o cursor retornado:

- GET /pix/batch/{cursor}

Note: a estrutura de retorno será a mesma do ' -GET pix/batch '.

4.2 Consultando Itens do lote

Consultar o item do batch é necessário para saber os status e detalhes de cada item que foi ou será processado.

Exemplo cURL: 

curl --location --request GET 'https://{URI}/pix/batch/{BatchID}/items' \
--header 'Atar-ApiKey: 00be0083-8c8d-**********' \
--header 'Authorization: Bearer eyJhbGciOi*************'

Exemplo de resposta: 

{
    "cursor": null,
    "data": [
        {
            "itemId": "ag5zfndlYXJhdGFyLWRldnIhCxIUVHJhbnNhY3Rpb25CYXRjaEl0ZW0YgIDAgunWwwoMogEDcGF5",
            "status": "waiting",
            "description": "Pagamento",
            "to": {
                "accountType": "checkingAccount",
                "accountNumber": "5685206537207808",
                "institutionName": "Atar",
                "key": "5547991271901",
                "branch": "0001",
                "document": "08959924938",
                "type": "phone",
                "institution": "19581142",
                "name": "Theo Victor Schlegel"
            },
            "amount": 10,
            "identifier": "02fb7933-6996-44cc-aaef-2b7683a130f6"
        }
    ]
}

Pontos de atenção:

Cursor: este campo faz o papel de uma paginação, quando este campo é diferente de null, isso significa que existe mais informações em uma outra pagina, para ter acesso a mesma deve executar o endpoint passando o cursor retornado:

- GET /pix/batch/{batchId}/items/{cursor}

Note: a estrutura de retorno será a mesma do '-GET /pix/batch/{batchId}/items' .

5. Comprovante

Utiliza-se o endpoint /pix/{pixId}/receipt para extrair o pdf dos pagamentos efetuados.

Com auxilio do eventos dos pagamentos recebidos pelo webhook, pode-se validar os detalhes de um pagamento e obter o id do pix(dado necessário efetuar a requisição no endpoint pix/{pixId}/receipt).

Exemplo do evento: 

{
    "atarId": 5645421468712960,
    "payload": {
        "subtitle": "R$ 0,10",
        "delayNotify": null,
        "eventTimestamp": "1662733190",
        "id": "ag5zfndlYXJhdGFyLWRldnIQCxIDUGl4GICAwPyMvdUIDKIBA3BheQ",
        "eventId": "ag5zfndlYXJhdGFyLWRldnISCxIFRXZlbnQYgIDA_Iy9lQsMogEDcGF5",
        "fee": 0,
        "from": {
            "key": null,
            "name": "Theo Victor Schlegel",
            "accountNumber": "5645421468712960",
            "institutionName": "Atar",
            "branch": "0001",
            "document": "08959924938",
            "institution": "19581142"
        },
        "title": "Pix para Mateus Tl Tres",
        "to": {
            "key": "11935610007",
            "accountType": "checkingAccount",
            "branch": "0001",
            "accountNumber": "118669929",
            "document": "11935610007",
            "institutionName": "Portoseg S.A. CFI",
            "institution": "04862600",
            "name": "Mateus Tl Tres"
        },
        "deviceType": null,
        "type": "output",
        "transactionStatus": "approved",
        "category": "pix_out",
        "description": "Pagamento",
        "transactionAccepted": true,
        "timestamp": "1662733153",
        "txId": null,
        "reason": null,
        "isRefund": false,
        "balanceAfter": 5196760,
        "atarId": 5645421468712960,
        "identifier": "02fb7933-6996-44cc-aaef-2b7683a130f6",
        "extraInfo": null,
        "endToEndId": "E195811422022090914180nHXhGiQCNI",
        "amount": 10,
        "transactionId": "4766293522644992",
        "transactionType": "debit"
    }
}

Endpoint 

- GET /pix/{pixId}/receipt

Exemplo cURL: 

curl --location --request GET '{URI}/pix/{pixId}/receipt' \
--header 'Atar-ApiKey: DB98D76A-4B12-********' \
--header 'Authorization: Bearer eyJhbGciOiJIU**********'

Exemplo de resposta: 

{
    "base64": "string" # comprovante em base64
    "name": "receipt.pdf",
    "description": "PDF de recebimento via PIX"
}

📘

Cadastre um serviço Webhook para receber todas as notificações de eventos das transações, de forma prática e eficaz.

6. Suporte

Central de ajuda Atar: Servide desk

Email: suporte@atarb2b.atlassian.net

7. Fluxograma

Note a numeração na frente da ação a ser realizada, o mesmo contém a identificação para localizar as informações no documento de integração.

Utilize a visualização para consultar o status do item ou do lote.
Note que pode ser utilizada de forma isolada.

1062

Ilustração do fluxo de funcionamento do serviço integrado.

Updated about 2 years ago

Did this page help you?

Updated about 2 years ago

Did this page help you?