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

📘

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.

📘

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.

📘

Webhooks

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