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.
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étodosPUT/PATCH/POST
que devem ser enviados no corpo da requisição, utilizando o formato JSON. Requisições no métodoGET
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 valorapplication/json
nos métodosPOST
ePUT
para especificar o formato das informações que você está enviando.A plataforma Vindi não suporta parâmetros no formato
form-data
oux-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.