Primeiros passos

Neste passo a passo você vai gerar um token, descobrir o endereço da sua agência e fazer a sua primeira requisição. Leva poucos minutos e, como a API é somente de leitura, você não altera nenhum dado da agência.

Antes de começar

Você precisa de:

• acesso ao painel administrativo da agência no Avoei, com permissão para gerenciar tokens de API;
• uma ferramenta para fazer requisições HTTP — o cURL no terminal, por exemplo.

1. Gere um token de API

No painel administrativo, vá em Configurações > API Tokens, clique em Criar API Token, dê um nome ao token (por exemplo, Site da agência) e copie o valor exibido.

Copie o token na hora

O token só é exibido uma vez. Guarde-o em um lugar seguro, como um gerenciador de senhas ou uma variável de ambiente.

O passo a passo completo está em Tokens de API.

2. Descubra o endereço da sua agência

Use o mesmo endereço em que os seus clientes acessam o site de vendas, seguido de /api/v1. Se o site é https://minhaagencia.avoei.com.br, a base da API é:

https://minhaagencia.avoei.com.br/api/v1

Nos exemplos desta documentação usamos minhaagencia.avoei.com.br. Troque pelo endereço da sua agência. Veja mais em URLs e ambientes.

3. Faça a primeira requisição

Vamos consultar os dados da empresa, que retorna um único objeto e é a chamada mais simples da API. Substitua SEU_TOKEN pelo token que você copiou.

cURL

curl https://minhaagencia.avoei.com.br/api/v1/companies \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"

JavaScript

const response = await fetch('https://minhaagencia.avoei.com.br/api/v1/companies', {
  headers: {
    Authorization: `Bearer ${process.env.AVOEI_TOKEN}`,
    Accept: 'application/json',
  },
});

const { data } = await response.json();
console.log(data.display_name ?? data.name);

PHP

$curl = curl_init('https://minhaagencia.avoei.com.br/api/v1/companies');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AVOEI_TOKEN'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($curl), true);
curl_close($curl);

echo $body['data']['display_name'] ?? $body['data']['name'];

Python

import os
import requests

response = requests.get(
    "https://minhaagencia.avoei.com.br/api/v1/companies",
    headers={
        "Authorization": f"Bearer {os.environ['AVOEI_TOKEN']}",
        "Accept": "application/json",
    },
)

data = response.json()["data"]
print(data.get("display_name") or data["name"])

Se tudo der certo, você recebe o status 200 e um JSON como este (resumido):

{
  "success": true,
  "message": "Company retrieved successfully",
  "data": {
    "id": 1,
    "name": "Aventuras do Vale Turismo LTDA",
    "display_name": "Aventuras do Vale",
    "document_type": "cnpj",
    "email": "[email protected]",
    "whatsapp_url": "https://wa.me/5524999990000",
    "address": {
      "city": "Resende",
      "state": "RJ"
    }
  },
  "errors": [],
  "status": 200
}

O objeto completo está descrito em Consultar a empresa.

Recebeu um erro?

• 401 — o token não foi enviado, está incorreto ou foi revogado. Confira o cabeçalho Authorization: Bearer SEU_TOKEN.
• 404 — confira o endereço da agência ou, se a resposta trouxer Company not found, se a agência já preencheu os dados da empresa.

Veja todos os casos em Erros.

4. Liste as próximas viagens

Agora vamos buscar as três próximas viagens da agência:

curl "https://minhaagencia.avoei.com.br/api/v1/travels?per_page=3" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Accept: application/json"

A lista vem dentro de data.data, junto de informações de paginação. Por padrão, ela mostra apenas viagens que ainda não começaram, da mais próxima para a mais distante. Para buscar por texto ou por período, veja Filtros.

Próximos passos

• Entenda o formato das respostas.
• Explore todos os endpoints na referência da API.
• Leia as boas práticas antes de colocar a integração no ar.