Playground API Emissões Efí: Como funciona?

Antes de colocar uma aplicação em produção, é muito importante que o desenvolvedor certifique-se de que sua implementação está correta e suas integrações estão comunicando da forma como deveriam.

Para evitar que os integradores tenham que fazer estes testes em produção, a Efí oferece um Ambiente de sandbox, que é um ambiente idêntico ao de produção, mas totalmente isolado, ou seja, cobranças criadas no ambiente de sandbox não são reais e são listadas na aba “Homologação” da aplicação. Nesta aba, o integrador pode conferir o histórico de requisições de sandbox e todas as cobranças geradas.

O integrador também pode utilizar as credenciais de teste nas SDKs ou o Playground da API para realizar seus testes em ambiente de sandbox.

Neste artigo será mostrado como o Playground pode ser utilizado para testar as funções da API.

Conhecendo o Playground 

O integrador deve acessar o menu “Minhas Aplicações” e clicar em “Nova Aplicação” para criar sua primeira aplicação e ter acesso à tela de Playground.

Esta tela mostra todos os endpoints disponibilizados pela API Emissões, ou seja, tudo que é possível fazer via integração.

As SDKs disponibilizadas pela Efí (em PHP, NodeJS, Python, Ruby e .NET) apenas abstraem esses endpoints em funções que facilitam a utilização, mas é no Playground que o integrador pode ter uma noção das informações que podem ser enviadas em cada situação, quais são obrigatórias, em quais formatos devem ser enviadas, etc.

Cada endpoint possui um campo editável para informar os dados de entrada¹ e um campo não-editável para mostrar o Schema². Os endpoints estão divididos em 4 grupos principais: Transações, Carnês, Notificações e Assinaturas.

¹Dados de Entrada: JSON com as informações que o endpoint deve receber para realizar a ação.
²Schema: JSON que descreve a estrutura dos dados, incluindo todas as informações que podem ser enviadas e as especificidades de cada uma.

Interpretando as respostas

Ao enviar um POST para a rota /charge, o integrador estará criando uma cobrança com status ‘new’. Esta cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento. Este endpoint é o equivalente à utilização da função createCharge() em qualquer SDK.

Um JSON simples que pode ser utilizado para criar uma cobrança no Playground é:

{  
   "items":[  
      {  
         "name":"Bola de Futebol",
         "value":1000,
         "amount":3
      }
   ]
}

Este JSON define que a cobrança deve possuir um produto de nome “Bola de Futebol”, valor R$ 10,00 e quantidade 3, ou seja, o valor total dessa cobrança será R$ 30,00.

A resposta deste consumo será:

{  
   "code":200,
   "data":{  
      "charge_id":70733,
      "status":"new",
      "total":3000,
      "custom_id":null,
      "created_at":"2016-06-28 14:36:49"
   }
}

O valor 200 para code mostra que o consumo foi realizado com sucesso. O valor de data mostra informações básicas sobre a cobrança criada. O integrador deve ter uma atenção especial com a informação de charge_id. Esse é o identificador da cobrança na API. Isso significa que, depois da criação, qualquer ação sobre a cobrança deverá ser realizada utilizando esse identificador.

Para definir uma forma de pagamento para a cobrança, o integrador deve optar entre boleto bancário ou cartão de crédito e utilizar o endpoint POST /charge/:id/pay. O identificador da URL é o identificador da cobrança recebido no consumo anterior (id: 70733).

Um exemplo de JSON que pode ser utilizado para definir o pagamento de uma cobrança como sendo Boleto Bancário:

{  
   "payment":{  
      "banking_billet":{  
         "customer":{  
            "name":"Gorbadoc Oldbuck",
            "cpf":"04267484171",
            "phone_number":"5144916523"
         },
         "expire_at":"2020-12-12",
         "discount":{  
            "type":"percentage",
            "value":500
         }
      }
   }
}

Neste exemplo, o integrador deseja que a cobrança 70733 seja paga via boleto bancário – definido pelo banking_billet – com data de vencimento para o dia 12/12/2020. O exemplo solicita 5% de desconto no valor total da cobrança e informa os dados obrigatórios do comprador.

A resposta desse consumo será:

{  
   "code":200,
   "data":{  
      "barcode":"00190.00009 01523.894002 00056.718182 5 84670000002850",
      "link":"https://visualizacaosandbox.gerencianet.com.br/emissao/93084_73_CORPA2/A4XB-93084-68009-HITA6",
      "expire_at":"2020-12-12",
      "charge_id":70733,
      "status":"waiting",
      "total":2850,
      "payment":"banking_billet"
   }
}

Dentre outras informações, a API informa o link do boleto bancário gerado e sua linha digitável. Neste momento a cobrança 70733 tem o status alterado para ‘waiting’. Isso significa que ela está aguardando o pagamento.

Possíveis Erros

Todo endpoint tem uma lista de códigos de erros que podem ser retornados em determinadas situações. Esta lista é importante para que o integrador consiga preparar sua integração para tratar todos os erros possíveis.

Para simular um erro, tente criar uma cobrança cujo valor total seja inferior a R$ 5,00:

{  
   "items":[  
      {  
         "name":"Bola de Futebol",
         "value":1,
         "amount":1
      }
   ]
}

Neste exemplo, a resposta será:

{  
   "code":3500034,
   "error":"validation_error",
   "error_description":"O valor total da cobrança deve ser maior ou igual a R$ 5,00."
}

A resposta possui code diferente de 200, ou seja, o consumo não teve sucesso. A API exige que o valor mínimo de uma cobrança seja de R$ 5,00, por isso, o erro 3500034 será retornado sempre que o integrador violar essa condição.

GET, POST, PUT e DELETE

A API é RESTful, isso significa que os endpoints criados seguem práticas específicas para que sejam intuitivos para os integradores que a utilizam.

Todo endpoint do tipo GET é de consulta, ou seja, o integrador nunca estará criando ou alterando um registro quando fizer um consumo deste tipo.

Os endpoints do tipo POST sempre estão relacionados à criação de algum registro. O POST /charge, cria uma cobrança. O POST /charge/:id/pay, cria um pagamento para uma determinada cobrança, e assim por diante.

Os endpoints do tipo PUT realizam a alteração de algum registro já existente. Quando o integrador utiliza PUT /charge/:id/cancel, por exemplo, ele está alterando o status de uma cobrança para canceled.

Por fim, os endpoints do tipo DELETE são responsáveis por deletar um registro. Esse tipo de consumo sempre vai solicitar um identificador para deleção. Na API, apenas planos de assinaturas podem ser deletados.

Conclusão

O Playground é a ferramenta ideal para o integrador que precisa testar, de forma rápida, se os dados que pretende enviar para a API Emissões estão corretos e seguem o padrão exigido.

O Schema mostra todas as informações possíveis que podem ser enviadas. Dessa forma, o integrador tem domínio de tudo que pode oferecer ao implementar seu sistema completo de criação e gestão de cobranças utilizando a Efí.

Explore mais essa ferramenta e descubra todas as possibilidades de integração que oferecemos! Acompanhe-nos e mantenha-se atualizado! Siga no Facebook, Twitter, Instagram e Linkendin!