Introdução à API de Recorrência da Vindi

API é o acrônimo de application programming interface, ou seja, a especificação da interface para integração entre sistemas. Neste artigo você irá encontrar todas as informações necessárias para integrar seu sistema à plataforma de pagamentos recorrentes da Vindi.

O objetivo da API é oferecer a possibilidade de estender as funcionalidades básicas da nossa plataforma, afim de integrar a recorrência em novas soluções ou em sistemas pré-existentes.

Requisitos

Para utilizar nossa API é necessário que você tenha familiaridade com a terminologia básica utilizada no desenvolvimento de web services REST. É possível desenvolver a integração com praticamente todas as linguagens de programação disponíveis no mercado.

Além do conhecimento técnico exigido, você deverá conhecer a plataforma Vindi do ponto de vista do usuário comum. Conceitos como "assinatura" e "fatura" deverão estar bem claros antes de iniciar o desenvolvimento. O artigo Entidades básicas da plataforma ajudará você a entender como as entidade básicas do sistema se relacionam.

Mapa de entidades

As entidades da plataforma Vindi relacionam-se da seguinte maneira:

Testes

Você pode testar a API Vindi através dos formulário dentro da própria documentação interativa (o link está no final deste documento). Para isso, informe a sua chave de acesso.

Também recomendamos a utilização do Postman, um plugin gratuito para o Chrome que facilita a inspeção de requisições e respostas.

Especificações técnicas

Formato

A API Vindi é um web service REST-compliant, ou seja, além dos métodos tradicionais POST e GET, você também verá aqui operações que utilizam os métodos PUT e DELETE. O retorno das requisições é realizado apenas no formato JSON, sempre acompanhado do código HTTP apropriado.

• Lista de códigos HTTP da API

Segurança e autenticação

A autenticação na API é realizada através do método HTTP Basic, utilizando a chave da API no campo destinado ao usuário, sem a necessidade de informar uma senha. Vale lembrar que a API Vindi só pode ser utilizada através do protocolo HTTPS. Por motivos de segurança, requisições HTTP não serão redirecionadas automaticamente para o protocolo HTTPS.

Para obter sua chave da API, acesse Configurações > Dados da empresa > Chaves de acesso.

Segue abaixo um exemplo de requisição utilizando o comando curl:

curl https://app.vindi.com.br/api/v1/payment_methods \
  -H Content-Type:application/json \
  -u API_KEY:

No exemplo acima, a autenticação é informada com o atributo -u no formato username:password. Conforme foi mencionado, não é necessário informar a senha, porém o separador ":" continua obrigatório (*).

Recomendamos a definição explícita do protocolo TLS v1.2 nos parâmetros da sua integração. Leia mais sobre o suporte à HTTPS, SSL e TLS.

---

(*) As autenticações em que o separador ":" não é informado, passarão a ter um retorno de 401 Unauthorized na resposta da requisição. Confira mais detalhes técnicos da obrigatoriedade nesse artigo.

Parâmetros

Cada método possui sua própria documentação para definir a forma de recepção de parâmetros. Para obter simetria entre envio e retorno, utilizamos atributos do tipo body nos métodos PUT/PATCH/POST que devem ser enviados no corpo da requisição, utilizando o formato JSON. Requisições no método GET podem receber parâmetros no path.

Convenção de nomenclatura

Alguns nomes de parâmetros se repetem em diferentes entidades da plataforma:

Parâmetros opcionais

Parâmetros opcionais podem ser simplesmente omitidos ou então informados com um valor nulo, usando null:

{ "code": null }

Content-Type da requisição

Informe o header Content-Type com o valor application/json nos métodos POST e PUT para especificar o formato das informações que você está enviando.

A plataforma Vindi não suporta parâmetros no formato form-data ou x-www-form-urlencoded.

Validando a sintaxe

Caso você receba a mensagem Bad request: Malformed syntax., verifique se o JSON enviado é válido. Você pode utilizar a ferramenta JSONLint para verificar sua sintaxe.

Retornos

Resultados com campos do tipo data/hora serão informados no padrão ISO 8601, respeitando o o fuso horário previamente configurado na plataforma. Parâmetros do tipo data/hora também deverão ser informados no formato ISO 8601.

Resultados que representam valores monetários serão sempre retornados como strings. Isto é necessário pois algumas bibliotecas JSON interpretam valores numéricos decimais automaticamente como ponto flutuante.

Paginação

Métodos identificados na documentação poderão retornar uma lista parcial de resultados caso ultrapassem o limite de registros por página. Nestes casos, na reposta serão informados os cabeçalhos Total, Per-Page e Link que auxiliarão na construção da requisição das próximas páginas:

Exemplo de cabeçalho de resposta:

Total: 72
Per-Page: 25
Link: <https://app.vindi.com.br/api/v1/customers?page=3>; rel="last", <https://app.vindi.com.br/api/v1/customers?page=2>; rel="next"

Recomendamos a utilização dos registros contidos no cabeçalho Link para efetuar a paginação. Também é possível informar a query string per_page para alterar o número de registros por página, limitado em 50 registros:

curl https://app.vindi.com.br/api/v1/customers?per_page=50 \
  -H Content-Type:application/json \
  -u API_KEY:

Buscas e filtros

Métodos de listagem que aceitam o parâmetro query podem receber filtros para especificar quais registros deverão ser retornados. Exemplo:

https://app.vindi.com.br/api/v1/customers?query=name:paulo

Através desta funcionalidade também é possível executar as seguintes pesquisas:

Para mais detalhes sobre a sintaxe da busca, consulte o artigo sobre Listas, buscas e filtros.

Dependendo do número de registros encontrados, poderá ser necessário efetuar a paginação, mencionada neste mesmo documento.

Limite de requisições

A plataforma Vindi possui um limite de 120 requisições por minuto, informado através de cabeçalhos no retorno. Para mais detalhes, consulte o artigo Limite de requisições.

Bibliotecas

No momento, dispomos de algumas bibliotecas oficiais que implementam nossa API:

• PHP: Vindi-PHP

Para outras linguagens, recomendamos a integração através de bibliotecas REST consolidadas:

• Java: HttpComponents Client
• Ruby: REST Client
• Python: Requests
• .NET: RestSharp

Você também pode utilizar qualquer outra biblioteca compatível com o padrão REST.

Versionamento e manutenção

A API Vindi está constante processo de evolução e novos métodos ou atributos podem ser adicionados a qualquer momento. Mesmo assim nos comprometemos, sempre que possível, a não efetuar nenhuma mudança que não seja retrocompatível. Nesses casos, uma nova versão será lançada e a versão antiga será mantida por um prazo determinado. Ainda assim, alterações que incompatibilizem implementações existentes poderão ocorrer em casos excepcionais, como por exemplo, em situações que envolvam riscos de segurança.

Considerando que novos atributos podem ser incluídos em métodos existentes, solicitamos que sua implementação não dependa da ordem dos atributos JSON na resposta da API. Faça a referência utilizando os nomes.

Segue abaixo um exemplo de implementação em pseudocódigo que deve ser evitado:

response = get('/api/v1/customers/1001')
customerId   = response[0]
customerName = response[1]
customerCode = response[5]

O código acima é extremamente frágil pois caso a Vindi insira um novo atributo no cliente, a implementação deixará de funcionar. Em vez disso, utilize como referência apenas os nomes definidos na documentação:

response = get('/api/v1/customers/1001')
customerId   = response['id']
customerName = response['name']
customerCode = response['code']

Webhooks

Além da API REST, a plataforma Vindi também suporta a configuração de webhooks. Consulte este artigo para mais detalhes.

Como eu uso a documentação interativa?

Dentro da plataforma, acesse o menu Configurações > Dados da Empresa > Chaves de acesso e gere sua chave da API privada. Acesse a documentação, cole a chave e clique em "Explorar".

Para consultar os parâmetros ou retornos de um método específico, clique no recurso desejado, no método e verifique a descrição e o exemplo JSON. É neste local que você deverá consultar a arquitetura das requisições e quais são os parâmetros obrigatórios e opcionais.

Dentro da documentação você será capaz de realizar requisições reais para a plataforma.

Apenas como curiosidade, a Vindi utiliza a especificação Swagger para documentar a API e disponibilizar a documentação interativa.

Leia também:

Modo Trial: quais números de cartões posso usar para teste?