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: [email protected]
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.
Ilustração do fluxo de funcionamento do serviço integrado.