Início

  • Visão geral
  • Referência da API

Guias

  • Comece em 5 minutos
  • Autenticação
  • Escopos
  • Paginação
  • Erros
  • Idempotência
  • Limites de requisição
  • Webhooks
  • Versionamento
  • Histórico de mudanças
Referência

Referência da API

58 operações, geradas do mesmo documento OpenAPI que a API serve. Endereço base: https://frotasimples.com/api.

Baixar o OpenAPI 3.1 · Baixar a coleção curl

Conta

GET/v1/conta

Conta e chave em uso

Devolve a Conta dona da chave, o plano e os escopos da chave. Use para conferir a chave.

Escopo: qualquer chave válida

Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/conta' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": 1,
  "nome": "texto",
  "plano": {
    "id": "texto",
    "nome": "texto"
  },
  "chave": {
    "prefixo": "texto",
    "nome": "texto",
    "escopos": [
      "texto"
    ]
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Frota

GET/v1/documentos

Lista os documentos

Filtros: `veiculoId`, `tipo` e `venceAte` (ISO 8601 com fuso — validade até esse instante). O arquivo não vem aqui: baixe por `GET /v1/documentos/{id}/arquivo`.

Escopo: documentos:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • veiculoId (consulta, string)
  • tipo (consulta, "CRLV" | "CNH" | "RNTRC" | "ANTT" | "SEGURO" | "IPVA" | "LICENCIAMENTO" | "OUTROS")
  • venceAte (consulta, string (date-time))
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "0b8f1d2e-6a7c-4e5f-9a1b-3c4d5e6f7a8b",
      "tipo": "CRLV",
      "numero": "123456789",
      "veiculoId": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
      "emissao": "2026-01-10T00:00:00.000Z",
      "validade": "2026-12-31T00:00:00.000Z",
      "situacao": "VALID",
      "verificado": false,
      "temArquivo": true,
      "nomeArquivo": "crlv-abc1d23.pdf",
      "tamanhoBytes": 182044,
      "mimeType": "application/pdf",
      "criadoEm": "2026-10-20T14:03:11.000Z",
      "atualizadoEm": "2026-10-20T14:03:11.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/documentos

Envia um documento

Corpo `multipart/form-data`: `arquivo` (PDF, JPG ou PNG, até 10 MB), `tipo` (CRLV, CNH, RNTRC, ANTT, SEGURO, IPVA, LICENCIAMENTO, OUTROS), `numero`, `emissao` e `validade` (ISO 8601 com fuso) e `veiculoId` (opcional). O tipo real do arquivo é lido dos bytes: extensão ou Content-Type que não batem com o conteúdo → 422. Gera `documento.criado`.

Escopo: documentos:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/documentos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)"

201 — Sucesso.

Resposta 201
{
  "id": "0b8f1d2e-6a7c-4e5f-9a1b-3c4d5e6f7a8b",
  "tipo": "CRLV",
  "numero": "123456789",
  "veiculoId": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "emissao": "2026-01-10T00:00:00.000Z",
  "validade": "2026-12-31T00:00:00.000Z",
  "situacao": "VALID",
  "verificado": false,
  "temArquivo": true,
  "nomeArquivo": "crlv-abc1d23.pdf",
  "tamanhoBytes": 182044,
  "mimeType": "application/pdf",
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/documentos/{id}

Exclui um documento

Apaga o registro e o arquivo. Gera `documento.excluido` com o último estado.

Escopo: documentos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/documentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/documentos/{id}

Um documento

Escopo: documentos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "0b8f1d2e-6a7c-4e5f-9a1b-3c4d5e6f7a8b",
  "tipo": "CRLV",
  "numero": "123456789",
  "veiculoId": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "emissao": "2026-01-10T00:00:00.000Z",
  "validade": "2026-12-31T00:00:00.000Z",
  "situacao": "VALID",
  "verificado": false,
  "temArquivo": true,
  "nomeArquivo": "crlv-abc1d23.pdf",
  "tamanhoBytes": 182044,
  "mimeType": "application/pdf",
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/documentos/{id}

Edita um documento

Parcial. Mudar `validade` recalcula `situacao`, salvo se ela vier no mesmo corpo. Para trocar o arquivo, envie um documento novo. Gera `documento.atualizado`.

Escopo: documentos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • numero (string)
  • emissao (string (date-time))
  • validade (string (date-time))
  • situacao ("VALID" | "EXPIRING_SOON" | "EXPIRED")
  • verificado (boolean)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/documentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"numero":"texto","emissao":"2026-10-20T12:00:00.000Z","validade":"2026-10-20T12:00:00.000Z","situacao":"VALID","verificado":true}'

200 — Sucesso.

Resposta 200
{
  "id": "0b8f1d2e-6a7c-4e5f-9a1b-3c4d5e6f7a8b",
  "tipo": "CRLV",
  "numero": "123456789",
  "veiculoId": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "emissao": "2026-01-10T00:00:00.000Z",
  "validade": "2026-12-31T00:00:00.000Z",
  "situacao": "VALID",
  "verificado": false,
  "temArquivo": true,
  "nomeArquivo": "crlv-abc1d23.pdf",
  "tamanhoBytes": 182044,
  "mimeType": "application/pdf",
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/documentos/{id}/arquivo

Baixa o arquivo de um documento

Devolve o arquivo em si (`application/pdf`, `image/jpeg` ou `image/png`, como `attachment`), não JSON. Todo download fica registrado na trilha de auditoria da Conta. Sem arquivo anexado → 404.

Escopo: documentos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos/{id}/arquivo' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso: o arquivo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/motoristas

Lista os motoristas

Inclui os inativos, salvo `ativo=true`. Filtros: `ativo`, `atualizadoDesde` (ISO 8601 com fuso). Traz CPF e CNH — dados pessoais (LGPD), só com o escopo `motoristas:ler`.

Escopo: motoristas:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • ativo (consulta, "true" | "false")
  • atualizadoDesde (consulta, string (date-time))
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/motoristas' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b",
      "nome": "João da Silva",
      "cpf": "12345678909",
      "telefone": "11988887777",
      "funcao": "Carreteiro",
      "admitidoEm": "2021-03-01T00:00:00.000Z",
      "atividadeRemunerada": true,
      "cnh": {
        "numero": "01234567890",
        "categoria": "E",
        "validade": "2027-05-10T00:00:00.000Z",
        "pontos": 7,
        "limitePontos": 40
      },
      "toxicologicoRealizadoEm": "2025-01-15T00:00:00.000Z",
      "toxicologicoValidade": "2027-07-15T00:00:00.000Z",
      "moppCertificado": "ANTT 118.442-9",
      "moppValidade": "2028-02-01T00:00:00.000Z",
      "origemDosDados": "MANUAL",
      "ativo": true,
      "criadoEm": "2026-10-20T14:03:11.000Z",
      "atualizadoEm": "2026-10-20T14:03:11.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/motoristas

Cadastra um motorista

CPF só com dígitos (máscara é removida). CPF já cadastrado na Conta → 409 `conflito`. Gera `motorista.criado`.

Escopo: motoristas:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • nome (string, obrigatório)
  • cpf (string, obrigatório)
  • funcao (string | null)
  • telefone (string | null)
  • admitidoEm (string | null)
  • atividadeRemunerada (boolean)
  • cnhNumero (string | null)
  • cnhCategoria ("A" | "B" | "C" | "D" | "E" | "AB" | "AC" | "AD" | "AE")
  • cnhValidade (string | null)
  • cnhPontos (integer)
  • cnhLimitePontos (integer)
  • toxicologicoRealizadoEm (string | null)
  • toxicologicoValidade (string | null)
  • moppCertificado (string | null)
  • moppValidade (string | null)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/motoristas' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"nome":"texto","cpf":"texto","funcao":"texto","telefone":"texto","admitidoEm":"texto","atividadeRemunerada":true,"cnhNumero":"texto","cnhCategoria":"A","cnhValidade":"texto","cnhPontos":0,"cnhLimitePontos":1,"toxicologicoRealizadoEm":"texto","toxicologicoValidade":"texto","moppCertificado":"texto","moppValidade":"texto"}'

201 — Sucesso.

Resposta 201
{
  "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b",
  "nome": "João da Silva",
  "cpf": "12345678909",
  "telefone": "11988887777",
  "funcao": "Carreteiro",
  "admitidoEm": "2021-03-01T00:00:00.000Z",
  "atividadeRemunerada": true,
  "cnh": {
    "numero": "01234567890",
    "categoria": "E",
    "validade": "2027-05-10T00:00:00.000Z",
    "pontos": 7,
    "limitePontos": 40
  },
  "toxicologicoRealizadoEm": "2025-01-15T00:00:00.000Z",
  "toxicologicoValidade": "2027-07-15T00:00:00.000Z",
  "moppCertificado": "ANTT 118.442-9",
  "moppValidade": "2028-02-01T00:00:00.000Z",
  "origemDosDados": "MANUAL",
  "ativo": true,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/motoristas/{id}

Inativa um motorista

Não apaga: marca `ativo: false` e devolve o motorista. Gera `motorista.excluido` com esse estado.

Escopo: motoristas:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/motoristas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b",
  "nome": "João da Silva",
  "cpf": "12345678909",
  "telefone": "11988887777",
  "funcao": "Carreteiro",
  "admitidoEm": "2021-03-01T00:00:00.000Z",
  "atividadeRemunerada": true,
  "cnh": {
    "numero": "01234567890",
    "categoria": "E",
    "validade": "2027-05-10T00:00:00.000Z",
    "pontos": 7,
    "limitePontos": 40
  },
  "toxicologicoRealizadoEm": "2025-01-15T00:00:00.000Z",
  "toxicologicoValidade": "2027-07-15T00:00:00.000Z",
  "moppCertificado": "ANTT 118.442-9",
  "moppValidade": "2028-02-01T00:00:00.000Z",
  "origemDosDados": "MANUAL",
  "ativo": true,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/motoristas/{id}

Um motorista

Traz CPF e CNH — dados pessoais (LGPD), só com o escopo `motoristas:ler`.

Escopo: motoristas:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/motoristas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b",
  "nome": "João da Silva",
  "cpf": "12345678909",
  "telefone": "11988887777",
  "funcao": "Carreteiro",
  "admitidoEm": "2021-03-01T00:00:00.000Z",
  "atividadeRemunerada": true,
  "cnh": {
    "numero": "01234567890",
    "categoria": "E",
    "validade": "2027-05-10T00:00:00.000Z",
    "pontos": 7,
    "limitePontos": 40
  },
  "toxicologicoRealizadoEm": "2025-01-15T00:00:00.000Z",
  "toxicologicoValidade": "2027-07-15T00:00:00.000Z",
  "moppCertificado": "ANTT 118.442-9",
  "moppValidade": "2028-02-01T00:00:00.000Z",
  "origemDosDados": "MANUAL",
  "ativo": true,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/motoristas/{id}

Edita um motorista

Parcial. Editar campo de CNH à mão faz `origemDosDados` voltar a `MANUAL`. `ativo: true` reativa. Gera `motorista.atualizado`.

Escopo: motoristas:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • nome (string)
  • cpf (string)
  • funcao (string | null)
  • telefone (string | null)
  • admitidoEm (string | null)
  • atividadeRemunerada (boolean)
  • cnhNumero (string | null)
  • cnhCategoria ("A" | "B" | "C" | "D" | "E" | "AB" | "AC" | "AD" | "AE")
  • cnhValidade (string | null)
  • cnhPontos (integer)
  • cnhLimitePontos (integer)
  • toxicologicoRealizadoEm (string | null)
  • toxicologicoValidade (string | null)
  • moppCertificado (string | null)
  • moppValidade (string | null)
  • ativo (boolean)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/motoristas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"nome":"texto","cpf":"texto","funcao":"texto","telefone":"texto","admitidoEm":"texto","atividadeRemunerada":true,"cnhNumero":"texto","cnhCategoria":"A","cnhValidade":"texto","cnhPontos":0,"cnhLimitePontos":1,"toxicologicoRealizadoEm":"texto","toxicologicoValidade":"texto","moppCertificado":"texto","moppValidade":"texto","ativo":true}'

200 — Sucesso.

Resposta 200
{
  "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b",
  "nome": "João da Silva",
  "cpf": "12345678909",
  "telefone": "11988887777",
  "funcao": "Carreteiro",
  "admitidoEm": "2021-03-01T00:00:00.000Z",
  "atividadeRemunerada": true,
  "cnh": {
    "numero": "01234567890",
    "categoria": "E",
    "validade": "2027-05-10T00:00:00.000Z",
    "pontos": 7,
    "limitePontos": 40
  },
  "toxicologicoRealizadoEm": "2025-01-15T00:00:00.000Z",
  "toxicologicoValidade": "2027-07-15T00:00:00.000Z",
  "moppCertificado": "ANTT 118.442-9",
  "moppValidade": "2028-02-01T00:00:00.000Z",
  "origemDosDados": "MANUAL",
  "ativo": true,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/veiculos

Lista os veículos

Mais recentes primeiro. Filtros: `placa` (exata), `status` e `atualizadoDesde` (ISO 8601 com fuso). Pagine com `cursor` = `paginacao.proximoCursor`.

Escopo: veiculos:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • placa (consulta, string)
  • status (consulta, "ACTIVE" | "INACTIVE" | "EXPIRED" | "PENDING")
  • atualizadoDesde (consulta, string (date-time))
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/veiculos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
      "placa": "ABC1D23",
      "renavam": "01234567890",
      "chassi": "9BM958074KB123456",
      "marca": "SCANIA",
      "modelo": "R450",
      "marcaModeloVersao": "SCANIA/R450 A6X2",
      "anoFabricacao": 2021,
      "anoModelo": 2022,
      "cor": "BRANCA",
      "categoria": "TRUCK",
      "status": "ACTIVE",
      "carroceria": "NAO APLICAVEL",
      "tipoCarroceria": "00",
      "tipoRodado": "03",
      "combustivel": "DIESEL",
      "eixos": 3,
      "taraKg": 9200,
      "capacidadeKg": 23000,
      "capacidadeM3": null,
      "pesoBrutoTotalKg": 23000,
      "cmtKg": 74000,
      "ufLicenciamento": "SP",
      "municipioLicenciamento": "CAMPINAS",
      "exercicioLicenciamento": 2026,
      "criadoEm": "2026-10-20T14:03:11.000Z",
      "atualizadoEm": "2026-10-20T14:03:11.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/veiculos

Cadastra um veículo

Placa já cadastrada → 409 `conflito`. Cota de veículos do plano esgotada → 409 `conflito`. Gera o evento `veiculo.criado`.

Escopo: veiculos:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • placa (string, obrigatório)
  • marca (string, obrigatório)
  • modelo (string, obrigatório)
  • anoFabricacao (integer, obrigatório)
  • categoria ("TRUCK" | "TRAILER" | "SEMI_TRAILER" | "TANKER" | "OTHER", obrigatório)
  • renavam (string)
  • chassi (string)
  • cor (string)
  • marcaModeloVersao (string | null)
  • anoModelo (integer | null)
  • carroceria (string | null)
  • combustivel (string | null)
  • eixos (integer | null)
  • capacidadeKg (number | string | null)
  • pesoBrutoTotalKg (integer | null)
  • cmtKg (integer | null)
  • ufLicenciamento (string | null)
  • municipioLicenciamento (string | null)
  • exercicioLicenciamento (integer | null)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/veiculos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"placa":"texto","marca":"texto","modelo":"texto","anoFabricacao":1900,"categoria":"TRUCK","renavam":"texto","chassi":"texto","cor":"texto","marcaModeloVersao":"texto","anoModelo":1900,"carroceria":"texto","combustivel":"texto","eixos":1,"capacidadeKg":1,"pesoBrutoTotalKg":1,"cmtKg":1,"ufLicenciamento":"texto","municipioLicenciamento":"texto","exercicioLicenciamento":1900}'

201 — Sucesso.

Resposta 201
{
  "id": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "placa": "ABC1D23",
  "renavam": "01234567890",
  "chassi": "9BM958074KB123456",
  "marca": "SCANIA",
  "modelo": "R450",
  "marcaModeloVersao": "SCANIA/R450 A6X2",
  "anoFabricacao": 2021,
  "anoModelo": 2022,
  "cor": "BRANCA",
  "categoria": "TRUCK",
  "status": "ACTIVE",
  "carroceria": "NAO APLICAVEL",
  "tipoCarroceria": "00",
  "tipoRodado": "03",
  "combustivel": "DIESEL",
  "eixos": 3,
  "taraKg": 9200,
  "capacidadeKg": 23000,
  "capacidadeM3": null,
  "pesoBrutoTotalKg": 23000,
  "cmtKg": 74000,
  "ufLicenciamento": "SP",
  "municipioLicenciamento": "CAMPINAS",
  "exercicioLicenciamento": 2026,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/veiculos/{id}

Exclui um veículo

Apaga o veículo e os documentos dele. Com multa ou lançamento financeiro vinculado → 409 `conflito`. Gera `veiculo.excluido` (e `documento.excluido` de cada documento).

Escopo: veiculos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/veiculos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/veiculos/{id}

Um veículo

Escopo: veiculos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/veiculos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "placa": "ABC1D23",
  "renavam": "01234567890",
  "chassi": "9BM958074KB123456",
  "marca": "SCANIA",
  "modelo": "R450",
  "marcaModeloVersao": "SCANIA/R450 A6X2",
  "anoFabricacao": 2021,
  "anoModelo": 2022,
  "cor": "BRANCA",
  "categoria": "TRUCK",
  "status": "ACTIVE",
  "carroceria": "NAO APLICAVEL",
  "tipoCarroceria": "00",
  "tipoRodado": "03",
  "combustivel": "DIESEL",
  "eixos": 3,
  "taraKg": 9200,
  "capacidadeKg": 23000,
  "capacidadeM3": null,
  "pesoBrutoTotalKg": 23000,
  "cmtKg": 74000,
  "ufLicenciamento": "SP",
  "municipioLicenciamento": "CAMPINAS",
  "exercicioLicenciamento": 2026,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/veiculos/{id}

Edita um veículo

Parcial. `null` limpa um campo opcional. Gera o evento `veiculo.atualizado`.

Escopo: veiculos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • placa (string)
  • marca (string)
  • modelo (string)
  • anoFabricacao (integer)
  • categoria ("TRUCK" | "TRAILER" | "SEMI_TRAILER" | "TANKER" | "OTHER")
  • renavam (string | null)
  • chassi (string | null)
  • cor (string | null)
  • marcaModeloVersao (string | null)
  • anoModelo (integer | null)
  • carroceria (string | null)
  • combustivel (string | null)
  • eixos (integer | null)
  • capacidadeKg (number | string | null)
  • pesoBrutoTotalKg (integer | null)
  • cmtKg (integer | null)
  • ufLicenciamento (string | null)
  • municipioLicenciamento (string | null)
  • exercicioLicenciamento (integer | null)
  • status ("ACTIVE" | "INACTIVE" | "EXPIRED" | "PENDING")
  • taraKg (number | string | null)
  • capacidadeM3 (number | string | null)
  • tipoRodado ("01" | "02" | "03" | "04" | "05" | "06")
  • tipoCarroceria ("00" | "01" | "02" | "03" | "04" | "05")
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/veiculos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"placa":"texto","marca":"texto","modelo":"texto","anoFabricacao":1900,"categoria":"TRUCK","renavam":"texto","chassi":"texto","cor":"texto","marcaModeloVersao":"texto","anoModelo":1900,"carroceria":"texto","combustivel":"texto","eixos":1,"capacidadeKg":1,"pesoBrutoTotalKg":1,"cmtKg":1,"ufLicenciamento":"texto","municipioLicenciamento":"texto","exercicioLicenciamento":1900,"status":"ACTIVE","taraKg":1,"capacidadeM3":1,"tipoRodado":"01","tipoCarroceria":"00"}'

200 — Sucesso.

Resposta 200
{
  "id": "5f0c6c1e-8d1a-4c1e-9f3a-2b7d1e0a9c41",
  "placa": "ABC1D23",
  "renavam": "01234567890",
  "chassi": "9BM958074KB123456",
  "marca": "SCANIA",
  "modelo": "R450",
  "marcaModeloVersao": "SCANIA/R450 A6X2",
  "anoFabricacao": 2021,
  "anoModelo": 2022,
  "cor": "BRANCA",
  "categoria": "TRUCK",
  "status": "ACTIVE",
  "carroceria": "NAO APLICAVEL",
  "tipoCarroceria": "00",
  "tipoRodado": "03",
  "combustivel": "DIESEL",
  "eixos": 3,
  "taraKg": 9200,
  "capacidadeKg": 23000,
  "capacidadeM3": null,
  "pesoBrutoTotalKg": 23000,
  "cmtKg": 74000,
  "ufLicenciamento": "SP",
  "municipioLicenciamento": "CAMPINAS",
  "exercicioLicenciamento": 2026,
  "criadoEm": "2026-10-20T14:03:11.000Z",
  "atualizadoEm": "2026-10-20T14:03:11.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/vencimentos

Lista os vencimentos

Vencidos e o que vence em até `dias` dias (0 a 365, padrão 30). Filtro `tipo`: TOXICOLOGICO, MOPP, CNH, VEICULOS ou EMPRESA. `dias` negativo no item = vencido há N dias.

Escopo: vencimentos:ler

Parâmetros

  • dias (consulta, integer | null)
  • tipo (consulta, "TOXICOLOGICO" | "MOPP" | "CNH" | "VEICULOS" | "EMPRESA")
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/vencimentos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "motorista:c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b:cnh",
      "tipo": "CNH",
      "titulo": "CNH categoria E — João da Silva",
      "subtitulo": "Renovação com exame toxicológico incluso",
      "data": "2026-11-10T00:00:00.000Z",
      "dias": 21,
      "recurso": {
        "tipo": "motorista",
        "id": "c2b9a7f4-3f1e-4b8e-a1f2-0c9d8e7f6a5b"
      }
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Multas

GET/v1/multas

Lista multas

Multas da Conta, das mais novas para as mais antigas. Filtros combinam entre si (E).

Escopo: multas:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • placa (consulta, string)
  • status (consulta, "PENDENTE" | "EM_ANALISE" | "CONTESTADA" | "PAGA" | "CANCELADA" | "VENCIDA")
  • venceAte (consulta, string)
  • atualizadoDesde (consulta, string (date-time))
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/multas' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "5b1f0c2e-8d7a-4c1e-9f3b-2a6d4e8c1b70",
      "numeroNotificacao": "SP123456789",
      "numeroProcesso": null,
      "orgao": "DETRAN-SP",
      "fonte": "DETRAN",
      "tipo": "SPEED",
      "codigoInfracao": "745-50",
      "descricao": "Transitar em velocidade superior à máxima permitida em até 20%",
      "local": "Rod. Anhanguera, km 45",
      "rodovia": "SP-330",
      "km": "45",
      "placa": "ABC1D23",
      "veiculoId": "0f6c3a8e-1b2d-4e5f-8a9b-7c6d5e4f3a21",
      "motoristaId": null,
      "valorOriginalCentavos": 13016,
      "descontoCentavos": 2603,
      "valorCentavos": 10413,
      "dataInfracao": "2026-10-02T14:30:00.000Z",
      "dataNotificacao": "2026-10-10T03:00:00.000Z",
      "vencimento": "2026-11-20T02:59:59.999Z",
      "vencimentoComDesconto": "2026-11-05T02:59:59.999Z",
      "prazoIndicacao": null,
      "status": "PENDENTE",
      "statusDetalhado": "NOTIFIED",
      "statusPagamento": "PENDING",
      "temDefesa": false,
      "temRecurso": false,
      "criadoEm": "2026-10-10T12:00:00.000Z",
      "atualizadoEm": "2026-10-10T12:00:00.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/multas

Registra uma multa

Cria a multa e a despesa a pagar correspondente no financeiro. O número de notificação é único: repetido responde 409.

Escopo: multas:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • veiculoId (string, obrigatório)
  • numeroNotificacao (string, obrigatório)
  • numeroProcesso (string)
  • orgao (string)
  • fonte ("DETRAN" | "DNIT" | "PRF" | "MUNICIPAL" | "OTHER")
  • tipo ("SPEED" | "RED_LIGHT" | "STOP_SIGN" | "PARKING" | "LANE_CHANGE" | "OVERTAKING" | "SEATBELT" | "PHONE_USE" | "DRUNK_DRIVING" | "VEHICLE_CONDITION" | "DOCUMENTATION" | "WEIGHT_LIMIT" | "HEIGHT_LIMIT" | "ENVIRONMENTAL" | "OTHER")
  • codigoInfracao (string, obrigatório)
  • descricao (string, obrigatório)
  • local (string, obrigatório)
  • rodovia (string)
  • km (string)
  • valorOriginalCentavos (integer, obrigatório)
  • descontoCentavos (integer)
  • valorCentavos (integer, obrigatório)
  • vencimento (string, obrigatório)
  • vencimentoComDesconto (string)
  • dataInfracao (string (date-time), obrigatório)
  • dataNotificacao (string (date-time))
  • motoristaId (string)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/multas' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"veiculoId":"texto","numeroNotificacao":"texto","numeroProcesso":"texto","orgao":"texto","fonte":"OTHER","tipo":"OTHER","codigoInfracao":"texto","descricao":"texto","local":"texto","rodovia":"texto","km":"texto","valorOriginalCentavos":1,"descontoCentavos":0,"valorCentavos":1,"vencimento":"texto","vencimentoComDesconto":"texto","dataInfracao":"2026-10-20T12:00:00.000Z","dataNotificacao":"2026-10-20T12:00:00.000Z","motoristaId":"texto"}'

201 — Sucesso.

Resposta 201
{
  "id": "5b1f0c2e-8d7a-4c1e-9f3b-2a6d4e8c1b70",
  "numeroNotificacao": "SP123456789",
  "numeroProcesso": null,
  "orgao": "DETRAN-SP",
  "fonte": "DETRAN",
  "tipo": "SPEED",
  "codigoInfracao": "745-50",
  "descricao": "Transitar em velocidade superior à máxima permitida em até 20%",
  "local": "Rod. Anhanguera, km 45",
  "rodovia": "SP-330",
  "km": "45",
  "placa": "ABC1D23",
  "veiculoId": "0f6c3a8e-1b2d-4e5f-8a9b-7c6d5e4f3a21",
  "motoristaId": null,
  "valorOriginalCentavos": 13016,
  "descontoCentavos": 2603,
  "valorCentavos": 10413,
  "dataInfracao": "2026-10-02T14:30:00.000Z",
  "dataNotificacao": "2026-10-10T03:00:00.000Z",
  "vencimento": "2026-11-20T02:59:59.999Z",
  "vencimentoComDesconto": "2026-11-05T02:59:59.999Z",
  "prazoIndicacao": null,
  "status": "PENDENTE",
  "statusDetalhado": "NOTIFIED",
  "statusPagamento": "PENDING",
  "temDefesa": false,
  "temRecurso": false,
  "criadoEm": "2026-10-10T12:00:00.000Z",
  "atualizadoEm": "2026-10-10T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/multas/{id}

Exclui uma multa cadastrada manualmente

Só multa de `fonte: OTHER` (cadastro manual) se exclui; a de órgão responde 409 — altere `status` para `CANCELADA`. A despesa em aberto vai junto; a já paga fica no financeiro.

Escopo: multas:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/multas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/multas/{id}

Detalha uma multa

Escopo: multas:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/multas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "5b1f0c2e-8d7a-4c1e-9f3b-2a6d4e8c1b70",
  "numeroNotificacao": "SP123456789",
  "numeroProcesso": null,
  "orgao": "DETRAN-SP",
  "fonte": "DETRAN",
  "tipo": "SPEED",
  "codigoInfracao": "745-50",
  "descricao": "Transitar em velocidade superior à máxima permitida em até 20%",
  "local": "Rod. Anhanguera, km 45",
  "rodovia": "SP-330",
  "km": "45",
  "placa": "ABC1D23",
  "veiculoId": "0f6c3a8e-1b2d-4e5f-8a9b-7c6d5e4f3a21",
  "motoristaId": null,
  "valorOriginalCentavos": 13016,
  "descontoCentavos": 2603,
  "valorCentavos": 10413,
  "dataInfracao": "2026-10-02T14:30:00.000Z",
  "dataNotificacao": "2026-10-10T03:00:00.000Z",
  "vencimento": "2026-11-20T02:59:59.999Z",
  "vencimentoComDesconto": "2026-11-05T02:59:59.999Z",
  "prazoIndicacao": null,
  "status": "PENDENTE",
  "statusDetalhado": "NOTIFIED",
  "statusPagamento": "PENDING",
  "temDefesa": false,
  "temRecurso": false,
  "criadoEm": "2026-10-10T12:00:00.000Z",
  "atualizadoEm": "2026-10-10T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/multas/{id}

Altera uma multa

`status` aceita a situação da tela (`PENDENTE`, `PAGA`, `CANCELADA`…). Valor e situação novos atualizam a despesa da multa no financeiro.

Escopo: multas:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • status ("PENDENTE" | "EM_ANALISE" | "CONTESTADA" | "PAGA" | "CANCELADA" | "VENCIDA")
  • valorCentavos (integer)
  • descricao (string)
  • local (string)
  • dataNotificacao (string (date-time))
  • motoristaId (string)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/multas/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"status":"PENDENTE","valorCentavos":1,"descricao":"texto","local":"texto","dataNotificacao":"2026-10-20T12:00:00.000Z","motoristaId":"texto"}'

200 — Sucesso.

Resposta 200
{
  "id": "5b1f0c2e-8d7a-4c1e-9f3b-2a6d4e8c1b70",
  "numeroNotificacao": "SP123456789",
  "numeroProcesso": null,
  "orgao": "DETRAN-SP",
  "fonte": "DETRAN",
  "tipo": "SPEED",
  "codigoInfracao": "745-50",
  "descricao": "Transitar em velocidade superior à máxima permitida em até 20%",
  "local": "Rod. Anhanguera, km 45",
  "rodovia": "SP-330",
  "km": "45",
  "placa": "ABC1D23",
  "veiculoId": "0f6c3a8e-1b2d-4e5f-8a9b-7c6d5e4f3a21",
  "motoristaId": null,
  "valorOriginalCentavos": 13016,
  "descontoCentavos": 2603,
  "valorCentavos": 10413,
  "dataInfracao": "2026-10-02T14:30:00.000Z",
  "dataNotificacao": "2026-10-10T03:00:00.000Z",
  "vencimento": "2026-11-20T02:59:59.999Z",
  "vencimentoComDesconto": "2026-11-05T02:59:59.999Z",
  "prazoIndicacao": null,
  "status": "PENDENTE",
  "statusDetalhado": "NOTIFIED",
  "statusPagamento": "PENDING",
  "temDefesa": false,
  "temRecurso": false,
  "criadoEm": "2026-10-10T12:00:00.000Z",
  "atualizadoEm": "2026-10-10T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Financeiro

GET/v1/contas-bancarias

Lista contas bancárias

Escopo: financeiro:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/contas-bancarias' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
      "nome": "Itaú — operacional",
      "banco": "Itaú",
      "ativa": true,
      "criadoEm": "2026-09-19T13:00:00.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/lancamentos

Lista lançamentos financeiros

Receitas e despesas da Conta, dos mais novos para os mais antigos. Despesa gerada por multa traz `multaId`.

Escopo: financeiro:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • tipo (consulta, "receita" | "despesa" | "transferencia")
  • status (consulta, "pendente" | "agendado" | "processando" | "liquidado" | "cancelado" | "falhou" | "vencido")
  • de (consulta, string)
  • ate (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/lancamentos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "9a2b7c4d-3e1f-4a6b-8c5d-0e9f8a7b6c5d",
      "tipo": "despesa",
      "categoria": "diesel",
      "descricao": "Abastecimento — Posto Graal km 120",
      "observacao": null,
      "valorCentavos": 185090,
      "data": "2026-10-15T15:00:00.000Z",
      "vencimento": "2026-10-15T15:00:00.000Z",
      "pagoEm": "2026-10-15T18:42:10.000Z",
      "status": "liquidado",
      "forma": "pix",
      "recorrente": false,
      "contaBancariaId": null,
      "multaId": null,
      "criadoEm": "2026-10-15T18:42:10.000Z",
      "atualizadoEm": "2026-10-15T18:42:10.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/lancamentos

Cria um lançamento

Conta a receber (`receita`) ou a pagar (`despesa`). `liquidado: true` lança já baixado, com a data de pagamento de agora. Receita é sempre da categoria `frete`.

Escopo: financeiro:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • tipo ("receita" | "despesa", obrigatório)
  • descricao (string, obrigatório)
  • observacao (string)
  • categoria ("diesel" | "pedagio" | "folha" | "parcela" | "manut" | "seguro" | "imposto" | "multa" | "outro")
  • forma ("boleto" | "pix" | "transferencia" | "dinheiro", obrigatório)
  • valorCentavos (integer, obrigatório)
  • vencimento (string, obrigatório)
  • recorrente (boolean)
  • liquidado (boolean)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/lancamentos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"tipo":"receita","descricao":"texto","observacao":"texto","categoria":"diesel","forma":"boleto","valorCentavos":1,"vencimento":"texto","recorrente":false,"liquidado":false}'

201 — Sucesso.

Resposta 201
{
  "id": "9a2b7c4d-3e1f-4a6b-8c5d-0e9f8a7b6c5d",
  "tipo": "despesa",
  "categoria": "diesel",
  "descricao": "Abastecimento — Posto Graal km 120",
  "observacao": null,
  "valorCentavos": 185090,
  "data": "2026-10-15T15:00:00.000Z",
  "vencimento": "2026-10-15T15:00:00.000Z",
  "pagoEm": "2026-10-15T18:42:10.000Z",
  "status": "liquidado",
  "forma": "pix",
  "recorrente": false,
  "contaBancariaId": null,
  "multaId": null,
  "criadoEm": "2026-10-15T18:42:10.000Z",
  "atualizadoEm": "2026-10-15T18:42:10.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/lancamentos/{id}

Exclui um lançamento

Escopo: financeiro:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/lancamentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/lancamentos/{id}

Detalha um lançamento

Escopo: financeiro:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/lancamentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "9a2b7c4d-3e1f-4a6b-8c5d-0e9f8a7b6c5d",
  "tipo": "despesa",
  "categoria": "diesel",
  "descricao": "Abastecimento — Posto Graal km 120",
  "observacao": null,
  "valorCentavos": 185090,
  "data": "2026-10-15T15:00:00.000Z",
  "vencimento": "2026-10-15T15:00:00.000Z",
  "pagoEm": "2026-10-15T18:42:10.000Z",
  "status": "liquidado",
  "forma": "pix",
  "recorrente": false,
  "contaBancariaId": null,
  "multaId": null,
  "criadoEm": "2026-10-15T18:42:10.000Z",
  "atualizadoEm": "2026-10-15T18:42:10.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/lancamentos/{id}

Altera um lançamento

Só o que vier no corpo muda. `liquidado: true` dá baixa (preserva a data de pagamento se já havia); `liquidado: false` estorna e limpa a data de pagamento.

Escopo: financeiro:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • tipo ("receita" | "despesa")
  • descricao (string)
  • observacao (string)
  • categoria ("diesel" | "pedagio" | "folha" | "parcela" | "manut" | "seguro" | "imposto" | "multa" | "outro")
  • forma ("boleto" | "pix" | "transferencia" | "dinheiro")
  • valorCentavos (integer)
  • vencimento (string)
  • recorrente (boolean)
  • liquidado (boolean)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/lancamentos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"tipo":"receita","descricao":"texto","observacao":"texto","categoria":"diesel","forma":"boleto","valorCentavos":1,"vencimento":"texto","recorrente":true,"liquidado":true}'

200 — Sucesso.

Resposta 200
{
  "id": "9a2b7c4d-3e1f-4a6b-8c5d-0e9f8a7b6c5d",
  "tipo": "despesa",
  "categoria": "diesel",
  "descricao": "Abastecimento — Posto Graal km 120",
  "observacao": null,
  "valorCentavos": 185090,
  "data": "2026-10-15T15:00:00.000Z",
  "vencimento": "2026-10-15T15:00:00.000Z",
  "pagoEm": "2026-10-15T18:42:10.000Z",
  "status": "liquidado",
  "forma": "pix",
  "recorrente": false,
  "contaBancariaId": null,
  "multaId": null,
  "criadoEm": "2026-10-15T18:42:10.000Z",
  "atualizadoEm": "2026-10-15T18:42:10.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Fiscal

GET/v1/documentos-fiscais

Lista documentos fiscais

CT-e, MDF-e e CIOT da Conta, do mais novo para o mais antigo. Rascunhos não aparecem. `de` e `ate` filtram pela data de emissão. A emissão pela API ainda não está disponível.

Escopo: fiscal:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • tipo (consulta, "cte" | "mdfe" | "ciot")
  • status (consulta, "assinando" | "autorizado" | "rejeitado" | "cancelado" | "encerrado" | "denegado")
  • de (consulta, string)
  • ate (consulta, string)
  • chaveAcesso (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos-fiscais' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "texto",
      "tipo": "cte",
      "modelo": "57",
      "serie": 1,
      "numero": 1,
      "chaveAcesso": "texto",
      "status": "assinando",
      "ambiente": "producao",
      "emitidoEm": "2026-10-20T12:00:00.000Z",
      "autorizadoEm": "2026-10-20T12:00:00.000Z",
      "canceladoEm": "2026-10-20T12:00:00.000Z",
      "motivoRejeicao": "texto",
      "valorTotalCentavos": 1,
      "tomador": {
        "nome": "texto",
        "documento": "texto",
        "inscricaoEstadual": "texto",
        "municipio": "texto",
        "codigoMunicipio": "texto",
        "uf": "texto"
      },
      "remetente": {
        "nome": "texto",
        "documento": "texto",
        "inscricaoEstadual": "texto",
        "municipio": "texto",
        "codigoMunicipio": "texto",
        "uf": "texto"
      },
      "destinatario": {
        "nome": "texto",
        "documento": "texto",
        "inscricaoEstadual": "texto",
        "municipio": "texto",
        "codigoMunicipio": "texto",
        "uf": "texto"
      },
      "rota": {
        "origem": {
          "municipio": "texto",
          "uf": "texto"
        },
        "destino": {
          "municipio": "texto",
          "uf": "texto"
        }
      },
      "detalhes": {
        "cfop": "texto",
        "naturezaOperacao": "texto",
        "valorCargaCentavos": 1,
        "valorReceberCentavos": 1,
        "valorIcmsCentavos": 1,
        "aliquotaIcmsBasisPoints": 1,
        "produtoPredominante": "texto",
        "pesoBrutoGramas": 1,
        "tomadorPapel": "texto",
        "ciotDocumentoId": "texto"
      },
      "criadoEm": "2026-10-20T12:00:00.000Z",
      "atualizadoEm": "2026-10-20T12:00:00.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/documentos-fiscais/{id}

Detalha um documento fiscal

Escopo: fiscal:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos-fiscais/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "tipo": "cte",
  "modelo": "57",
  "serie": 1,
  "numero": 1,
  "chaveAcesso": "texto",
  "status": "assinando",
  "ambiente": "producao",
  "emitidoEm": "2026-10-20T12:00:00.000Z",
  "autorizadoEm": "2026-10-20T12:00:00.000Z",
  "canceladoEm": "2026-10-20T12:00:00.000Z",
  "motivoRejeicao": "texto",
  "valorTotalCentavos": 1,
  "tomador": {
    "nome": "texto",
    "documento": "texto",
    "inscricaoEstadual": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto"
  },
  "remetente": {
    "nome": "texto",
    "documento": "texto",
    "inscricaoEstadual": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto"
  },
  "destinatario": {
    "nome": "texto",
    "documento": "texto",
    "inscricaoEstadual": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto"
  },
  "rota": {
    "origem": {
      "municipio": "texto",
      "uf": "texto"
    },
    "destino": {
      "municipio": "texto",
      "uf": "texto"
    }
  },
  "detalhes": {
    "cfop": "texto",
    "naturezaOperacao": "texto",
    "valorCargaCentavos": 1,
    "valorReceberCentavos": 1,
    "valorIcmsCentavos": 1,
    "aliquotaIcmsBasisPoints": 1,
    "produtoPredominante": "texto",
    "pesoBrutoGramas": 1,
    "tomadorPapel": "texto",
    "ciotDocumentoId": "texto"
  },
  "criadoEm": "2026-10-20T12:00:00.000Z",
  "atualizadoEm": "2026-10-20T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/documentos-fiscais/{id}/pdf

DACTE ou DAMDFE em PDF

DACTE para CT-e autorizado; DAMDFE para MDF-e autorizado ou encerrado. Outros casos (inclusive CIOT) respondem 409.

Escopo: fiscal:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos-fiscais/{id}/pdf' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso: o arquivo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/documentos-fiscais/{id}/xml

XML autorizado do documento fiscal

Disponível para documentos autorizados, cancelados ou encerrados. Antes disso responde 409.

Escopo: fiscal:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/documentos-fiscais/{id}/xml' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso: o arquivo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Processos

GET/v1/processos

Lista processos ANTT

Pedidos de serviço ANTT da Conta, do mais recente ao mais antigo. Exige o módulo ANTT (Contas de carga).

Escopo: processos:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • numero (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/processos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "texto",
      "numero": "texto",
      "servico": {
        "tipo": "texto",
        "nome": "texto"
      },
      "status": "pendente",
      "statusDoPedido": "PENDING",
      "pagamento": {
        "status": "PENDING",
        "pagoEm": "texto"
      },
      "criadoEm": "texto",
      "atualizadoEm": "texto",
      "historico": [
        {
          "status": "PENDING",
          "em": "texto"
        }
      ]
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/processos/{id}

Um processo ANTT

Escopo: processos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/processos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "numero": "texto",
  "servico": {
    "tipo": "texto",
    "nome": "texto"
  },
  "status": "pendente",
  "statusDoPedido": "PENDING",
  "pagamento": {
    "status": "PENDING",
    "pagoEm": "texto"
  },
  "criadoEm": "texto",
  "atualizadoEm": "texto",
  "historico": [
    {
      "status": "PENDING",
      "em": "texto"
    }
  ]
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Webhooks

GET/v1/webhooks

Lista os webhooks da Conta

Todos os endpoints cadastrados, com a última entrega de cada um. O segredo nunca aparece aqui.

Escopo: webhooks:gerenciar

Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/webhooks' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "url": "texto",
      "descricao": "texto",
      "eventos": [
        "texto"
      ],
      "ativo": true,
      "desativadoEm": "2026-10-20T12:00:00.000Z",
      "motivoDesativacao": "texto",
      "falhasConsecutivas": 1,
      "ultimaEntrega": {
        "status": "PENDENTE",
        "statusHttp": 1,
        "em": "2026-10-20T12:00:00.000Z"
      },
      "criadoEm": "2026-10-20T12:00:00.000Z",
      "atualizadoEm": "2026-10-20T12:00:00.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/webhooks

Cadastra um webhook

A URL precisa ser `https://` na porta 443 e apontar para um endereço público. Só é possível assinar tipos de evento cujo escopo de leitura a chave tem. A resposta traz o `segredo` de assinatura — a única vez em que ele é exibido. Cada entrega leva `FrotaSimples-Assinatura: t=<unix>,v1=<HMAC-SHA256(segredo, t + "." + corpo)>`; confira a assinatura e recuse `t` com mais de 5 minutos.

Escopo: webhooks:gerenciar

Corpo (JSON)

  • url (string, obrigatório)
  • eventos (string[], obrigatório) — Tipos de evento assinados, ou `["*"]` para todos.
  • descricao (string | null)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/webhooks' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://erp.exemplo.com.br/webhooks/frotasimples","eventos":["veiculo.criado"],"descricao":"texto"}'

201 — Sucesso.

Resposta 201
{
  "webhook": {
    "id": "00000000-0000-4000-8000-000000000000",
    "url": "texto",
    "descricao": "texto",
    "eventos": [
      "texto"
    ],
    "ativo": true,
    "desativadoEm": "2026-10-20T12:00:00.000Z",
    "motivoDesativacao": "texto",
    "falhasConsecutivas": 1,
    "ultimaEntrega": {
      "status": "PENDENTE",
      "statusHttp": 1,
      "em": "2026-10-20T12:00:00.000Z"
    },
    "criadoEm": "2026-10-20T12:00:00.000Z",
    "atualizadoEm": "2026-10-20T12:00:00.000Z"
  },
  "segredo": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/webhooks/{id}

Exclui um webhook

Exclui o endpoint e o histórico de entregas dele.

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/webhooks/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/webhooks/{id}

Um webhook

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/webhooks/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "00000000-0000-4000-8000-000000000000",
  "url": "texto",
  "descricao": "texto",
  "eventos": [
    "texto"
  ],
  "ativo": true,
  "desativadoEm": "2026-10-20T12:00:00.000Z",
  "motivoDesativacao": "texto",
  "falhasConsecutivas": 1,
  "ultimaEntrega": {
    "status": "PENDENTE",
    "statusHttp": 1,
    "em": "2026-10-20T12:00:00.000Z"
  },
  "criadoEm": "2026-10-20T12:00:00.000Z",
  "atualizadoEm": "2026-10-20T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/webhooks/{id}

Altera um webhook

Troca URL, eventos ou descrição. `ativo: true` reativa um webhook desativado (por falha ou à mão) e zera as falhas; `ativo: false` desativa e descarta as entregas pendentes.

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • url (string)
  • eventos (string[]) — Tipos de evento assinados, ou `["*"]` para todos.
  • descricao (string | null)
  • ativo (boolean) — `true` reativa um webhook desativado e zera as falhas.
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/webhooks/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://erp.exemplo.com.br/webhooks/frotasimples","eventos":["veiculo.criado"],"descricao":"texto","ativo":true}'

200 — Sucesso.

Resposta 200
{
  "id": "00000000-0000-4000-8000-000000000000",
  "url": "texto",
  "descricao": "texto",
  "eventos": [
    "texto"
  ],
  "ativo": true,
  "desativadoEm": "2026-10-20T12:00:00.000Z",
  "motivoDesativacao": "texto",
  "falhasConsecutivas": 1,
  "ultimaEntrega": {
    "status": "PENDENTE",
    "statusHttp": 1,
    "em": "2026-10-20T12:00:00.000Z"
  },
  "criadoEm": "2026-10-20T12:00:00.000Z",
  "atualizadoEm": "2026-10-20T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/webhooks/{id}/entregas

Histórico de entregas

Status, último HTTP, tentativas, próxima tentativa e último erro de cada entrega.

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
  • limite (consulta, integer)
  • cursor (consulta, string)
  • status (consulta, "PENDENTE" | "ENTREGUE" | "FALHOU" | "DESCARTADA")
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/webhooks/{id}/entregas' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "evento": {
        "id": "texto",
        "tipo": "texto"
      },
      "status": "PENDENTE",
      "tentativas": 1,
      "proximaTentativaEm": "2026-10-20T12:00:00.000Z",
      "ultimoStatusHttp": 1,
      "ultimoErro": "texto",
      "ultimaDuracaoMs": 1,
      "entregueEm": "2026-10-20T12:00:00.000Z",
      "criadoEm": "2026-10-20T12:00:00.000Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/webhooks/{id}/entregas/{entregaId}/reenviar

Reenvia uma entrega

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
  • entregaId (caminho, string, obrigatório)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/webhooks/{id}/entregas/{entregaId}/reenviar' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "00000000-0000-4000-8000-000000000000",
  "evento": {
    "id": "texto",
    "tipo": "texto"
  },
  "status": "PENDENTE",
  "tentativas": 1,
  "proximaTentativaEm": "2026-10-20T12:00:00.000Z",
  "ultimoStatusHttp": 1,
  "ultimoErro": "texto",
  "ultimaDuracaoMs": 1,
  "entregueEm": "2026-10-20T12:00:00.000Z",
  "criadoEm": "2026-10-20T12:00:00.000Z"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/webhooks/{id}/rotacionar-segredo

Rotaciona o segredo de assinatura

Gera um segredo novo, exibido só nesta resposta. Entregas a partir de agora são assinadas com ele.

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/webhooks/{id}/rotacionar-segredo' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "segredo": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/webhooks/{id}/testar

Envia um evento de teste

Entrega `teste.ping` agora, assinado com o segredo do endpoint. Responde com o status HTTP e a duração.

Escopo: webhooks:gerenciar

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/webhooks/{id}/testar' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "sucesso": true,
  "statusHttp": 1,
  "duracaoMs": 1,
  "erro": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Eventos

GET/v1/eventos

Lista eventos

Mais recentes primeiro, com cursor. Filtros `tipo` e `desde`. Além de `eventos:ler`, cada tipo exige o escopo de leitura do domínio dele (ex.: `veiculo.*` exige `veiculos:ler`): tipos sem escopo simplesmente não aparecem.

Escopo: eventos:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • tipo (consulta, string)
  • desde (consulta, string (date-time)) — ISO 8601 com fuso.
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/eventos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "texto",
      "tipo": "texto",
      "versao": 1,
      "recursoId": "texto",
      "criadoEm": "2026-10-20T12:00:00.000Z",
      "dados": null
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/eventos/{id}

Um evento

Escopo: eventos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/eventos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "tipo": "texto",
  "versao": 1,
  "recursoId": "texto",
  "criadoEm": "2026-10-20T12:00:00.000Z",
  "dados": null
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Carteira

GET/v1/carteira

Saldo da carteira de consultas

Créditos disponíveis e os retidos por consultas em andamento.

Escopo: carteira:ler

Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/carteira' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "saldo": 42,
  "reservado": 1
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/carteira/extrato

Extrato da carteira de consultas

Compras, consumos e ajustes, dos mais novos para os mais antigos.

Escopo: carteira:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/carteira/extrato' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "3f2e1d0c-9b8a-4766-8554-433221100fed",
      "tipo": "consumption",
      "origem": "routine",
      "quantidade": -1,
      "saldoApos": 41,
      "descricao": "Consulta de débitos — ABC1D23",
      "criadoEm": "2026-10-18T09:00:12.345Z"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Clientes

GET/v1/clientes

Lista clientes

Clientes do Atendimento, do mais recente ao mais antigo. Arquivados só com `arquivados=true`.

Escopo: clientes:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • documento (consulta, string) — CNPJ/CPF, com ou sem pontuação.
  • arquivados (consulta, "true" | "false") — `true` inclui os arquivados.
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/clientes' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "texto",
      "tipoPessoa": "PJ",
      "razaoSocial": "texto",
      "nomeFantasia": "texto",
      "documento": "texto",
      "inscricaoEstadual": "texto",
      "email": "texto",
      "telefone": "texto",
      "endereco": {
        "logradouro": "texto",
        "numero": "texto",
        "complemento": "texto",
        "bairro": "texto",
        "municipio": "texto",
        "codigoMunicipio": "texto",
        "uf": "texto",
        "cep": "texto"
      },
      "segmento": "texto",
      "arquivadoEm": "texto",
      "criadoEm": "texto",
      "atualizadoEm": "texto"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/clientes

Cria um cliente

Documento já cadastrado nesta Conta responde 409 `conflito` com o id existente no `detail` e em `Location` — é o caminho do upsert: em vez de criar de novo, atualize com PATCH.

Escopo: clientes:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • tipoPessoa ("PJ" | "PF") — Padrão: PJ.
  • razaoSocial (string, obrigatório)
  • nomeFantasia (string | null)
  • documento (string | null) — CNPJ ou CPF, com ou sem pontuação. Confere o dígito.
  • inscricaoEstadual (string | null)
  • email (string (email) | null (email))
  • telefone (string | null)
  • segmento (string | null)
  • endereco (object)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/clientes' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"tipoPessoa":"PJ","razaoSocial":"texto","nomeFantasia":"texto","documento":"texto","inscricaoEstadual":"texto","email":"[email protected]","telefone":"texto","segmento":"texto","endereco":{"logradouro":"texto","numero":"texto","complemento":"texto","bairro":"texto","municipio":"texto","codigoMunicipio":"texto","uf":"texto","cep":"texto"}}'

201 — Sucesso.

Resposta 201
{
  "id": "texto",
  "tipoPessoa": "PJ",
  "razaoSocial": "texto",
  "nomeFantasia": "texto",
  "documento": "texto",
  "inscricaoEstadual": "texto",
  "email": "texto",
  "telefone": "texto",
  "endereco": {
    "logradouro": "texto",
    "numero": "texto",
    "complemento": "texto",
    "bairro": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto",
    "cep": "texto"
  },
  "segmento": "texto",
  "arquivadoEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/clientes/{id}

Um cliente

Arquivado também abre (com `arquivadoEm`).

Escopo: clientes:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/clientes/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "tipoPessoa": "PJ",
  "razaoSocial": "texto",
  "nomeFantasia": "texto",
  "documento": "texto",
  "inscricaoEstadual": "texto",
  "email": "texto",
  "telefone": "texto",
  "endereco": {
    "logradouro": "texto",
    "numero": "texto",
    "complemento": "texto",
    "bairro": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto",
    "cep": "texto"
  },
  "segmento": "texto",
  "arquivadoEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/clientes/{id}

Atualiza um cliente

Parcial: campo ausente não muda; `null` apaga. Documento de outro cliente desta Conta → 409.

Escopo: clientes:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • tipoPessoa ("PJ" | "PF") — Padrão: PJ.
  • razaoSocial (string)
  • nomeFantasia (string | null)
  • documento (string | null) — CNPJ ou CPF, com ou sem pontuação. Confere o dígito.
  • inscricaoEstadual (string | null)
  • email (string (email) | null (email))
  • telefone (string | null)
  • segmento (string | null)
  • endereco (object)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/clientes/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"tipoPessoa":"PJ","razaoSocial":"texto","nomeFantasia":"texto","documento":"texto","inscricaoEstadual":"texto","email":"[email protected]","telefone":"texto","segmento":"texto","endereco":{"logradouro":"texto","numero":"texto","complemento":"texto","bairro":"texto","municipio":"texto","codigoMunicipio":"texto","uf":"texto","cep":"texto"}}'

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "tipoPessoa": "PJ",
  "razaoSocial": "texto",
  "nomeFantasia": "texto",
  "documento": "texto",
  "inscricaoEstadual": "texto",
  "email": "texto",
  "telefone": "texto",
  "endereco": {
    "logradouro": "texto",
    "numero": "texto",
    "complemento": "texto",
    "bairro": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto",
    "cep": "texto"
  },
  "segmento": "texto",
  "arquivadoEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/clientes/{id}/arquivar

Arquiva um cliente

Arquivar de novo um cliente já arquivado devolve o mesmo cliente (200).

Escopo: clientes:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/clientes/{id}/arquivar' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "tipoPessoa": "PJ",
  "razaoSocial": "texto",
  "nomeFantasia": "texto",
  "documento": "texto",
  "inscricaoEstadual": "texto",
  "email": "texto",
  "telefone": "texto",
  "endereco": {
    "logradouro": "texto",
    "numero": "texto",
    "complemento": "texto",
    "bairro": "texto",
    "municipio": "texto",
    "codigoMunicipio": "texto",
    "uf": "texto",
    "cep": "texto"
  },
  "segmento": "texto",
  "arquivadoEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.

Contatos

GET/v1/contatos

Lista contatos

Contatos do Atendimento, do mais recente ao mais antigo.

Escopo: contatos:ler

Parâmetros

  • limite (consulta, integer)
  • cursor (consulta, string)
  • telefone (consulta, string) — Com DDD; acha com e sem o 9º dígito.
  • email (consulta, string)
  • clienteId (consulta, string)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/contatos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "dados": [
    {
      "id": "texto",
      "nome": "texto",
      "telefone": "texto",
      "email": "texto",
      "cargo": "COMERCIAL",
      "principal": true,
      "clienteId": "texto",
      "optOutEm": "texto",
      "criadoEm": "texto",
      "atualizadoEm": "texto"
    }
  ],
  "paginacao": {
    "proximoCursor": "texto",
    "temMais": true
  }
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
POST/v1/contatos

Cria um contato

Exige e-mail ou telefone. Identificador já em uso nesta Conta → 409 `conflito` com o id existente no `detail` e em `Location`.

Escopo: contatos:escrever

Parâmetros

  • Idempotency-Key (cabeçalho, string, obrigatório) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • nome (string | null)
  • telefone (string | null) — Com DDD; o `55` é acrescentado se faltar.
  • email (string | null)
  • cargo ("COMERCIAL" | "FINANCEIRO" | "FISCAL" | "OPERACIONAL" | "MOTORISTA" | "DIRETORIA" | "OUTRO")
  • principal (boolean) — Só vale com `clienteId`. Rebaixa o principal anterior.
  • clienteId (string | null)
Exemplo — curl
curl -X POST 'https://frotasimples.com/api/v1/contatos' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"nome":"texto","telefone":"texto","email":"texto","cargo":"COMERCIAL","principal":true,"clienteId":"texto"}'

201 — Sucesso.

Resposta 201
{
  "id": "texto",
  "nome": "texto",
  "telefone": "texto",
  "email": "texto",
  "cargo": "COMERCIAL",
  "principal": true,
  "clienteId": "texto",
  "optOutEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
DELETE/v1/contatos/{id}

Exclui um contato

Apaga a ficha; as conversas ficam, anonimizadas. Contato com negócio → 409 (mescle ou exclua o negócio antes).

Escopo: contatos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X DELETE 'https://frotasimples.com/api/v1/contatos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

204 — Sucesso, sem corpo.

Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
GET/v1/contatos/{id}

Um contato

Escopo: contatos:ler

Parâmetros

  • id (caminho, string, obrigatório)
Exemplo — curl
curl -X GET 'https://frotasimples.com/api/v1/contatos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE"

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "nome": "texto",
  "telefone": "texto",
  "email": "texto",
  "cargo": "COMERCIAL",
  "principal": true,
  "clienteId": "texto",
  "optOutEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
PATCH/v1/contatos/{id}

Atualiza um contato

Parcial: campo ausente não muda; `null` apaga (mas nunca e-mail e telefone juntos). Identificador de outra ficha desta Conta → 409.

Escopo: contatos:escrever

Parâmetros

  • id (caminho, string, obrigatório)
  • Idempotency-Key (cabeçalho, string) — Uma chave única por operação (ex.: UUID). Válida por 24 h.

Corpo (JSON)

  • nome (string | null)
  • telefone (string | null) — Com DDD; o `55` é acrescentado se faltar.
  • email (string | null)
  • cargo ("COMERCIAL" | "FINANCEIRO" | "FISCAL" | "OPERACIONAL" | "MOTORISTA" | "DIRETORIA" | "OUTRO")
  • principal (boolean) — Só vale com `clienteId`. Rebaixa o principal anterior.
  • clienteId (string | null)
Exemplo — curl
curl -X PATCH 'https://frotasimples.com/api/v1/contatos/{id}' \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"nome":"texto","telefone":"texto","email":"texto","cargo":"COMERCIAL","principal":true,"clienteId":"texto"}'

200 — Sucesso.

Resposta 200
{
  "id": "texto",
  "nome": "texto",
  "telefone": "texto",
  "email": "texto",
  "cargo": "COMERCIAL",
  "principal": true,
  "clienteId": "texto",
  "optOutEm": "texto",
  "criadoEm": "texto",
  "atualizadoEm": "texto"
}
Erros possíveis
  • 401 — Chave ausente, inválida, revogada ou expirada.
  • 403 — Plano sem API, escopo insuficiente ou módulo desativado na Conta.
  • 404 — Recurso inexistente — inclusive quando pertence a outra Conta.
  • 422 — Corpo, consulta ou Idempotency-Key inválidos.
  • 429 — Limite de requisições excedido. Respeite o Retry-After.
  • 500 — Erro interno. Repita com a mesma Idempotency-Key.
Frota Simples

Empresa privada de tecnologia para gestão de frota. Veículos, documentos, multas e a burocracia com os órgãos em um só painel.

Serviços

  • Conheça a plataforma
  • Gestão de frota
  • Integrações
  • Gestão de Multas
  • Consultas
  • Cadastro ANTT
  • Renovação ANTT
  • Inclusão de Veículos
  • Alteração Cadastral

Suporte

  • Perguntas Frequentes
  • Status do Sistema
  • Desenvolvedores

Contato

  • [email protected]E-mail oficial
© 2026 — Todos os direitos reservados.
Política de PrivacidadeTermos de UsoAcessibilidadeCancelamento e Reembolso