Introdução à API de Recorrência

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.

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 > API & Webhooks.

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.

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:

id Identificação interna na plataforma Vindi. Este número é único para toda a plataforma dentro do escopo de cada entidade e é gerado automaticamente.
code Código externo opcional para referência via API. Popule este campo com seu próprio código único. A validação de unicidade é realizada dentro do escopo de cada entidade e conta.
created_at Data da criação da entidade.
updated_at Data da última atualização da entidade.

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:

Total Total de registros em todas as páginas
Per-Page Número máximo de registros por página
Link URLs relacionadas (Hypermedia)

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:

name:paulo Busca por registros contendo a string "paulo" (case insensitive) no campo "nome".
code=42 Busca o único cliente com o campo do código externo exatamente igual a "42" .
created_at>=2015-01-15 Clientes criados a partir do dia 15/01/2015.
status:active AND email:gmail.com Clientes ativos com o email contendo a string "gmail.com".

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:

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

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.

Lista de métodos de parâmetros

Para obter uma lista completa de todos os métodos e parâmetros disponíveis, acesse a documentação da API. Você precisará informar sua chave de acesso que se encontra no menu Configurações > Dados da empresa > API & Webhooks. Consulte o artigo Como utilizar a documentação interativa para obter mais detalhes.

Tem mais dúvidas? Envie uma solicitação

Comentários

Powered by Zendesk