Módulos v2

Módulo e-CRLV — API v2

5 min de leituraVale para v2

Acesso

Disponível somente entrando em contato com o suporte.

Solicite a emissão do e-CRLV (Certificado de Registro e Licenciamento de Veículo digital) dos veículos da sua frota direto pela API. Primeiro você descobre quais veículos podem ter o documento solicitado; depois abre a solicitação para o veículo escolhido, acompanha o andamento e baixa o documento quando ele estiver pronto.

O que dá para fazer

Ação	Endpoint	Quando usar
Listar veículos elegíveis	`GET /v2/crlv/eligible-vehicles`	Descobrir quais veículos da frota podem ter o e-CRLV solicitado
Solicitar e-CRLV	`POST /v2/crlv/requests`	Abrir a solicitação de emissão para um veículo elegível
Consultar uma solicitação	`GET /v2/crlv/requests/{requestId}`	Acompanhar o status de uma solicitação e baixar o documento quando concluída
Consultar e-CRLV por placa	`GET /v2/crlv/vehicles/{carPlate}`	Obter o último documento emitido de um veículo e a solicitação em andamento, se houver

Processamento assíncrono

A solicitação não devolve o documento na mesma requisição. A API registra o pedido e responde com status: pending e a previsão de disponibilização (expectedBy). Acompanhe o andamento em Consultar uma solicitação.

Antes de começar

Pré-requisitos

Antes de usar este módulo, certifique-se de ter:

Acesso ao módulo — o e-CRLV precisa estar habilitado para a sua organização. Sem o acesso, a API retorna 403. Solicite no onboarding.
Credenciais HMAC — Access Token e Secret Key fornecidos no onboarding.

Autenticação

Este módulo usa a mesma autenticação HMAC-SHA256 da API v1 — sem novas credenciais. Veja os headers obrigatórios e o cálculo da assinatura no Guia de Autenticação HMAC.

Correlation ID (opcional)

Envie o header x-correlation-id: {UUID} para rastrear a requisição nos logs. Se ausente, a API gera um automaticamente.

Listar veículos elegíveis

GET/v2/crlv/eligible-vehicles

Retorna, de forma paginada, os veículos ativos da sua organização que podem ter o e-CRLV solicitado. Use o vehicleId retornado aqui para abrir a solicitação.

Parâmetros de query

Parâmetro	Obrigatório	Tipo	Padrão	Descrição
`currentPage`	Não	integer	`1`	Número da página. Mínimo `1`.
`pageSize`	Não	integer	`10`	Itens por página. Entre `1` e `100`.
`carPlate`	Não	string	—	Filtro exato por placa. Aceita com ou sem hífen e em minúsculas — a API normaliza para o formato `ABC1D23`. Aceita placas no padrão antigo e Mercosul.

Exemplo de requisição

curl -X GET \
  'https://api.sandbox.v2.frota162.com.br/v2/crlv/eligible-vehicles?currentPage=1&pageSize=10' \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta (`200 OK`)

{
  "data": [
    {
      "vehicleId": 101,
      "carPlate": "ABC1D23",
      "uf": "SP"
    }
  ],
  "page": {
    "currentPage": 1,
    "pageSize": 10,
    "totalItems": 25,
    "totalPages": 3,
    "hasNext": true
  }
}

Campos de `data[]`

Campo	Tipo	Descrição
`vehicleId`	integer	Identificador do veículo. Use no `POST /v2/crlv/requests`.
`carPlate`	string	Placa do veículo.
`uf`	string \| null	UF de licenciamento do veículo. Pode vir `null`.

Campos de `page`

Campo	Tipo	Descrição
`currentPage`	integer	Página atual.
`pageSize`	integer	Itens por página.
`totalItems`	integer	Total de veículos elegíveis.
`totalPages`	integer	Total de páginas.
`hasNext`	boolean	`true` se existe próxima página.

Lista vazia

Quando nenhum veículo é elegível (ou o filtro por placa não encontra nada), a API responde 200 com data: [].

Solicitar e-CRLV

POST/v2/crlv/requests

Abre a solicitação de emissão do e-CRLV do exercício atual para um veículo. A API valida o veículo, registra o pedido e responde com a previsão de disponibilização do documento.

Corpo da requisição

{
  "vehicleId": 101
}

Campo	Obrigatório	Tipo	Descrição
`vehicleId`	Sim	integer	Identificador do veículo, obtido em `GET /v2/crlv/eligible-vehicles`. Inteiro positivo, até `2147483647`.

Corpo estrito

O corpo aceita somente vehicleId. Qualquer campo adicional retorna 400.

Regras de elegibilidade

O veículo precisa pertencer à sua organização.
O proprietário do veículo precisa ser pessoa jurídica (CNPJ).
Só existe uma solicitação em andamento por veículo. Uma nova solicitação para o mesmo veículo, enquanto a anterior está aberta, retorna 409.
O e-CRLV é emitido uma vez por exercício. Se o documento do ano atual já foi emitido, a API retorna 409.

Exemplo de requisição

curl -X POST \
  'https://api.sandbox.v2.frota162.com.br/v2/crlv/requests' \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}' \
  -H 'Content-Type: application/json' \
  -d '{ "vehicleId": 101 }'

Resposta (`201 Created`)

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "vehicleId": 101,
  "carPlate": "ABC1D23",
  "status": "pending",
  "requestedAt": "2026-09-30T10:00:00.000Z",
  "expectedBy": "2026-10-02T10:00:00.000Z"
}

Campo	Tipo	Descrição
`requestId`	string (UUID)	Identificador da solicitação. Guarde para acompanhar o pedido em `GET /v2/crlv/requests/{requestId}` e para falar com o suporte.
`vehicleId`	integer	Identificador do veículo.
`carPlate`	string	Placa do veículo.
`status`	string	Sempre `pending` na criação.
`requestedAt`	string (ISO 8601)	Data e hora da solicitação.
`expectedBy`	string (ISO 8601)	Previsão de disponibilização do documento — 2 dias úteis após a solicitação, contados no horário de Brasília.

Consultar uma solicitação

GET/v2/crlv/requests/{requestId}

Retorna o status atual de uma solicitação aberta pela sua organização. Quando a emissão é concluída, a resposta traz o documento com uma URL temporária para download do PDF.

Parâmetros de path

Parâmetro	Obrigatório	Tipo	Descrição
`requestId`	Sim	string (UUID)	Identificador retornado no `POST /v2/crlv/requests`.

Exemplo de requisição

curl -X GET \
  'https://api.sandbox.v2.frota162.com.br/v2/crlv/requests/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta (`200 OK`)

Solicitação concluída:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "vehicleId": 101,
  "carPlate": "ABC1D23",
  "status": "completed",
  "requestedAt": "2026-09-30T10:00:00.000Z",
  "expectedBy": "2026-10-02T10:00:00.000Z",
  "document": {
    "exerciseYear": 2026,
    "issuedAt": "2026-10-01T14:00:00.000Z",
    "downloadUrl": "https://files.example.com/crlv/550e8400.pdf?signature=abc",
    "downloadUrlExpiresAt": "2026-10-01T15:00:00.000Z"
  },
  "failure": null
}

Solicitação com falha:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "vehicleId": 101,
  "carPlate": "ABC1D23",
  "status": "failed",
  "requestedAt": "2026-09-30T10:00:00.000Z",
  "expectedBy": "2026-10-02T10:00:00.000Z",
  "document": null,
  "failure": {
    "code": "CRLV_ISSUE_FAILED",
    "message": "Não foi possível emitir o e-CRLV deste veículo."
  }
}

Campo	Tipo	Descrição
`requestId`	string (UUID)	Identificador da solicitação.
`vehicleId`	integer	Identificador do veículo.
`carPlate`	string	Placa do veículo.
`status`	string	Status da solicitação. Veja Status da solicitação.
`requestedAt`	string (ISO 8601)	Data e hora da solicitação.
`expectedBy`	string (ISO 8601) ou `null`	Previsão de disponibilização do documento.
`document`	objeto ou `null`	Documento emitido. Presente somente quando `status` é `completed`.
`document.exerciseYear`	integer	Ano de exercício do documento.
`document.issuedAt`	string (ISO 8601) ou `null`	Data e hora de emissão do documento.
`document.downloadUrl`	string	URL temporária para download do PDF.
`document.downloadUrlExpiresAt`	string (ISO 8601)	Expiração da `downloadUrl`.
`failure`	objeto ou `null`	Motivo da falha. Presente somente quando `status` é `failed`.
`failure.code`	string	Código público da falha.
`failure.message`	string	Mensagem pública da falha.

URL de download temporária

A downloadUrl vale por 1 hora (downloadUrlExpiresAt). Baixe e armazene o PDF do seu lado; se a URL expirar, consulte a solicitação de novo para receber uma URL nova. Não guarde a URL para uso posterior.

Status da solicitação

`status`	Significado	O que fazer
`pending`	Solicitação registrada, aguardando emissão.	Consultar novamente mais tarde.
`in_progress`	Emissão em andamento.	Consultar novamente mais tarde.
`completed`	Documento emitido e disponível em `document`.	Baixar o PDF pela `downloadUrl`.
`failed`	Não foi possível emitir o documento. O motivo está em `failure`.	Resultado final da solicitação. Se precisar, contate o suporte informando o `requestId`.

completed e failed são finais: a solicitação não muda mais de status.

Frequência de consulta

A emissão leva até 2 dias úteis (expectedBy). Evite consultar em intervalos curtos — uma consulta a cada poucas horas é suficiente enquanto o status for pending ou in_progress.

Consultar e-CRLV por placa

GET/v2/crlv/vehicles/{carPlate}

Retorna, para um veículo ativo da sua organização, o último e-CRLV emitido e a solicitação em andamento, quando existirem. Use quando você tem a placa, mas não o requestId.

Parâmetros de path

Parâmetro	Obrigatório	Tipo	Descrição
`carPlate`	Sim	string	Placa do veículo. Aceita com ou sem hífen e em minúsculas — a API normaliza para o formato `ABC1D23`. Aceita placas no padrão antigo e Mercosul.

Exemplo de requisição

curl -X GET \
  'https://api.sandbox.v2.frota162.com.br/v2/crlv/vehicles/ABC1D23' \
  -H 'Authorization: Basic {ACCESS_TOKEN}' \
  -H 'Key: {HMAC_SIGNATURE}'

Resposta (`200 OK`)

{
  "vehicleId": 101,
  "carPlate": "ABC1D23",
  "uf": "SP",
  "latestDocument": {
    "exerciseYear": 2026,
    "issuedAt": "2026-10-01T14:00:00.000Z",
    "downloadUrl": "https://files.example.com/crlv/550e8400.pdf?signature=abc",
    "downloadUrlExpiresAt": "2026-10-01T15:00:00.000Z"
  },
  "openRequest": null
}

Campo	Tipo	Descrição
`vehicleId`	integer	Identificador do veículo.
`carPlate`	string	Placa do veículo.
`uf`	string ou `null`	UF de registro do veículo.
`latestDocument`	objeto ou `null`	Último e-CRLV emitido para o veículo. `null` quando não há documento disponível.
`latestDocument.exerciseYear`	integer	Ano de exercício do documento.
`latestDocument.issuedAt`	string (ISO 8601) ou `null`	Data e hora de emissão do documento.
`latestDocument.downloadUrl`	string	URL temporária para download do PDF. Vale por 1 hora.
`latestDocument.downloadUrlExpiresAt`	string (ISO 8601)	Expiração da `downloadUrl`.
`openRequest`	objeto ou `null`	Solicitação em andamento aberta pela API para o veículo. `null` quando não há nenhuma.
`openRequest.requestId`	string (UUID)	Identificador da solicitação. Use em `GET /v2/crlv/requests/{requestId}`.
`openRequest.status`	string	`pending` ou `in_progress`.
`openRequest.requestedAt`	string (ISO 8601)	Data e hora da solicitação.
`openRequest.expectedBy`	string (ISO 8601) ou `null`	Previsão de disponibilização do documento.

Um veículo sem documento e sem solicitação em andamento retorna 200 com latestDocument: null e openRequest: null.

Referência de erros

Formato RFC 7807

A API v2 retorna erros no padrão RFC 7807 Problem Details. Veja o Guia de Tratamento de Erros para a referência completa.

Todos os erros retornam o seguinte formato:

{
  "type": "urn:frota162-api-v2:error:{tipo}",
  "title": "Título do erro",
  "status": 409,
  "detail": "Descrição específica do problema",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123def456"
}

Erros por status

400 — Requisição inválida

Listagem: currentPage ou pageSize fora dos limites, ou carPlate em formato inválido.

Solicitação: vehicleId ausente, não inteiro, não positivo, acima de 2147483647, ou corpo com campos adicionais.

Consulta de solicitação: requestId não é um UUID válido.

Consulta por placa: carPlate em formato inválido.

{
  "type": "urn:frota162-api-v2:error:validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Placa inválida",
  "instance": "/v2/crlv/eligible-vehicles",
  "traceId": "abc123"
}

401 — Autenticação ausente ou inválida

Header Authorization: Basic {ACCESS_TOKEN} ou Key: {HMAC_SIGNATURE} ausente, ou assinatura HMAC inválida.

{
  "type": "urn:frota162-api-v2:error:unauthorized",
  "title": "Unauthorized Access",
  "status": 401,
  "detail": "Missing required header: Authorization",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123"
}

403 — Sem acesso ao módulo

O e-CRLV não está habilitado para a sua organização, ou a conta não tem organização configurada. Entre em contato para solicitar acesso.

{
  "type": "urn:frota162-api-v2:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Organização sem acesso ao e-CRLV",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123"
}

404 — Veículo ou solicitação não encontrada

O type indica o que não foi encontrado:

`type`	Endpoint	Quando
`vehicle-not-found`	Solicitação	O `vehicleId` não existe ou não pertence à sua organização.
`vehicle-not-found`	Consulta por placa	Nenhum veículo ativo da sua organização tem a placa informada.
`crlv-request-not-found`	Consulta de solicitação	O `requestId` não existe ou pertence a outra organização.

{
  "type": "urn:frota162-api-v2:error:crlv-request-not-found",
  "title": "CRLV Request Not Found",
  "status": 404,
  "detail": "Solicitação de CRLV não encontrada",
  "instance": "/v2/crlv/requests/550e8400-e29b-41d4-a716-446655440000",
  "traceId": "abc123"
}

409 — Conflito com uma solicitação existente

Somente na solicitação. O type indica o motivo:

`type`	Quando
`crlv-request-already-open`	Já existe uma solicitação em andamento para o veículo. Quando disponível, a resposta traz o `requestId` da solicitação aberta.
`crlv-already-issued-this-year`	O e-CRLV do exercício atual já foi emitido para o veículo.
`crlv-retry-window`	A solicitação está dentro da janela de reprocessamento. Aguarde antes de solicitar novamente.

{
  "type": "urn:frota162-api-v2:error:crlv-request-already-open",
  "title": "Request Already Open",
  "status": 409,
  "detail": "Já existe uma solicitação de CRLV em andamento para este veículo",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

422 — Veículo não elegível

Somente na solicitação. O veículo existe, mas não pode ter o e-CRLV emitido. O type indica o motivo:

`type`	Quando
`crlv-owner-not-legal-entity`	O proprietário do veículo é pessoa física ou o documento do proprietário não é CNPJ.
`crlv-unsupported-vehicle`	O veículo não é suportado para emissão digital do CRLV.
`crlv-plan-not-allowed`	O plano contratado não permite a emissão do CRLV.
`crlv-vehicle-inactive`	O veículo está inativo.

{
  "type": "urn:frota162-api-v2:error:crlv-owner-not-legal-entity",
  "title": "Owner Not Legal Entity",
  "status": 422,
  "detail": "Veículo pertence a pessoa física ou documento do proprietário não é CNPJ",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123"
}

429 — Limite de requisições

Somente na solicitação. O limite de requisições foi atingido. O header Retry-After indica quantos segundos aguardar. Veja Rate Limiting.

500 — Erro interno

Falha inesperada ao processar a requisição. Se persistir, contate o suporte informando o traceId.

{
  "type": "urn:frota162-api-v2:error:internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123"
}

503 — Serviço temporariamente indisponível

O serviço de e-CRLV está temporariamente indisponível. Aguarde o tempo indicado no header Retry-After (em segundos, normalmente 60) e envie novamente.

Solicitação: nenhuma solicitação fica aberta.
Consultas: o status da solicitação não é alterado; basta repetir a consulta.

{
  "type": "urn:frota162-api-v2:error:service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The service is temporarily unavailable. Please try again later",
  "instance": "/v2/crlv/requests",
  "traceId": "abc123",
  "retryAfter": 60
}

Referência rápida

Status	`type`	Aplica-se a	Causa	Ação
`400`	`validation-error`	Todos	Parâmetro ou corpo inválido	Revisar a requisição
`401`	`unauthorized` / `authentication-failed`	Todos	Header ausente ou HMAC inválido	Revisar headers e recalcular HMAC
`403`	`forbidden`	Todos	Organização sem acesso ao módulo	Solicitar acesso
`404`	`vehicle-not-found`	Solicitação	Veículo inexistente ou de outra organização	Verificar o `vehicleId`
`404`	`vehicle-not-found`	Consulta por placa	Nenhum veículo ativo com a placa	Verificar a placa
`404`	`crlv-request-not-found`	Consulta de solicitação	Solicitação inexistente ou de outra organização	Verificar o `requestId`
`409`	`crlv-request-already-open`	Solicitação	Solicitação em andamento para o veículo	Aguardar a solicitação aberta
`409`	`crlv-already-issued-this-year`	Solicitação	e-CRLV do exercício já emitido	Não reenviar
`409`	`crlv-retry-window`	Solicitação	Dentro da janela de reprocessamento	Aguardar e retentar
`422`	`crlv-owner-not-legal-entity`	Solicitação	Proprietário não é pessoa jurídica	Resultado definitivo — não reenviar
`422`	`crlv-unsupported-vehicle`	Solicitação	Veículo não suportado	Resultado definitivo — não reenviar
`422`	`crlv-plan-not-allowed`	Solicitação	Plano não permite a emissão	Contatar o suporte
`422`	`crlv-vehicle-inactive`	Solicitação	Veículo inativo	Reativar o veículo e retentar
`429`	`rate-limit-exceeded`	Solicitação	Limite de requisições atingido	Aguardar `Retry-After` e retentar
`500`	`internal-server-error`	Todos	Falha inesperada	Retentar com backoff; contatar o suporte se persistir
`503`	`service-unavailable`	Todos	Serviço temporariamente indisponível	Aguardar `Retry-After` e retentar

Próximos passos

VeículosGerencie sua frota

Cadastre e mantenha os veículos que podem ter o e-CRLV solicitado.

Primeiros PassosComece a integrar

Configure seu ambiente e faça sua primeira chamada à API.

O que dá para fazer​

Antes de começar​

Pré-requisitos​

Autenticação​

Listar veículos elegíveis​

Parâmetros de query​

Exemplo de requisição​

Resposta (200 OK)​

Campos de data[]​

Campos de page​

Solicitar e-CRLV​

Corpo da requisição​

Regras de elegibilidade​

Exemplo de requisição​

Resposta (201 Created)​

Consultar uma solicitação​

Parâmetros de path​

Exemplo de requisição​

Resposta (200 OK)​

Status da solicitação​

Consultar e-CRLV por placa​

Parâmetros de path​

Exemplo de requisição​

Resposta (200 OK)​

Referência de erros​

Erros por status​

Referência rápida​

Próximos passos​

O que dá para fazer

Antes de começar

Pré-requisitos

Autenticação

Listar veículos elegíveis

Parâmetros de query

Exemplo de requisição

Resposta (`200 OK`)

Campos de `data[]`

Campos de `page`

Solicitar e-CRLV

Corpo da requisição

Regras de elegibilidade

Exemplo de requisição

Resposta (`201 Created`)

Consultar uma solicitação

Parâmetros de path

Exemplo de requisição

Resposta (`200 OK`)

Status da solicitação

Consultar e-CRLV por placa

Parâmetros de path

Exemplo de requisição

Resposta (`200 OK`)

Referência de erros

Erros por status

Referência rápida

Próximos passos