Documentação da API

Bem-vindo à documentação da API do APVBot. Nossa API permite que você integre as funcionalidades do APVBot diretamente em seus sistemas e aplicativos.

Autenticação

A API do APVBot utiliza tokens de API para autenticação. Você pode gerar um token no painel de controle do APVBot.

Obter seu token de API

1. Faça login no seu painel de controle do APVBot
2. Navegue até Configurações > API
3. Clique em "Gerar novo token"
4. Copie e armazene seu token em um local seguro

Usar o token de API

Inclua seu token de API no cabeçalho Authorization de todas as requisições:

curl -X GET "https://api.apvbot.com/v1/cotacoes" \
  -H "Authorization: Bearer SEU_TOKEN_API"

Endpoints

{
  "data": [
    {
      "id": "cot_123456789",
      "cliente": {
        "nome": "João Silva",
        "telefone": "+5511999999999"
      },
      "veiculo": {
        "marca": "Toyota",
        "modelo": "Corolla",
        "ano": 2020,
        "valor_fipe": 90000
      },
      "valor": 150.00,
      "status": "pendente",
      "criado_em": "2023-01-15T14:30:00Z"
    },
    // ...mais cotações
  ],
  "meta": {
    "total": 45,
    "limit": 10,
    "offset": 0
  }
}

{
  "erro": "Token de API inválido ou expirado"
}

{
  "cliente": {
    "nome": "Maria Oliveira",
    "telefone": "+5511988888888",
    "email": "maria@exemplo.com"
  },
  "veiculo": {
    "marca": "Honda",
    "modelo": "Civic",
    "ano": 2021,
    "placa": "ABC1234"
  }
}

{
  "id": "cot_987654321",
  "cliente": {
    "nome": "Maria Oliveira",
    "telefone": "+5511988888888",
    "email": "maria@exemplo.com"
  },
  "veiculo": {
    "marca": "Honda",
    "modelo": "Civic",
    "ano": 2021,
    "placa": "ABC1234",
    "valor_fipe": 110000
  },
  "valor": 180.00,
  "status": "pendente",
  "criado_em": "2023-06-20T10:15:00Z"
}

{
  "erro": "Dados inválidos",
  "detalhes": {
    "veiculo.placa": "Placa inválida"
  }
}

{
  "data": [
    {
      "id": "cli_123456789",
      "nome": "João Silva",
      "telefone": "+5511999999999",
      "email": "joao@exemplo.com",
      "criado_em": "2023-01-10T09:30:00Z"
    },
    // ...mais clientes
  ],
  "meta": {
    "total": 28,
    "limit": 10,
    "offset": 0
  }
}

{
  "url": "https://seu-site.com/webhook",
  "eventos": ["cotacao.criada", "cotacao.aprovada", "cliente.novo"]
}

{
  "id": "wh_123456789",
  "url": "https://seu-site.com/webhook",
  "eventos": ["cotacao.criada", "cotacao.aprovada", "cliente.novo"],
  "ativo": true,
  "criado_em": "2023-06-20T14:30:00Z"
}

Erros

A API do APVBot utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Em geral, códigos na faixa 2xx indicam sucesso, códigos 4xx indicam um erro que foi causado pela informação fornecida (por exemplo, um parâmetro obrigatório estava ausente), e códigos 5xx indicam um erro no servidor do APVBot.

Limites de taxa

Para garantir a estabilidade e disponibilidade da API para todos os usuários, implementamos limites de taxa nas requisições à API. Os limites variam de acordo com o seu plano:

Quando você excede o limite de taxa, a API retornará um código de status HTTP 429 (Too Many Requests). Os seguintes cabeçalhos são incluídos em todas as respostas para ajudar você a gerenciar seus limites:

Paginação

Para endpoints que retornam listas de objetos, a API do APVBot utiliza paginação baseada em offset para permitir que você navegue pelos resultados. Você pode controlar a paginação usando os seguintes parâmetros:

As respostas paginadas incluem um objeto meta com informações sobre a paginação:

{
  "data": [
    // ... objetos retornados
  ],
  "meta": {
    "total": 45,    // Total de objetos disponíveis
    "limit": 10,    // Limite usado na requisição
    "offset": 0     // Offset usado na requisição
  }
}

Versionamento

A API do APVBot é versionada para garantir que as mudanças não quebrem integrações existentes. A versão atual é v1.

Você pode especificar a versão da API de duas maneiras:

1. No URL (recomendado):
   https://api.apvbot.com/v1/cotacoes
2. No cabeçalho Accept:
   Accept: application/json; version=1