API REST · v1

Integre o seu sistema ao estoque IntegraRenave

A API do IntegraRenave permite consultar o controle completo do estoque e conectar o seu DMS ou qualquer base de dados para atualização automática — em tempo real via webhooks ou por sincronização incremental.

Base URL: https://api.integrarenave.com.br/api/v1

Autenticação

Toda requisição leva a sua chave no header X-API-Key. A chave é gerada no painel (seção API), tem o formato ir_live_… e é exibida uma única vez — armazenamos apenas o hash (SHA-256). Chaves ir_test_… operam em sandbox, sem cobrança.

curl "https://api.integrarenave.com.br/api/v1/status" \
  -H "X-API-Key: ir_live_SUA_CHAVE"

HTTPS obrigatório — requisições em HTTP puro são rejeitadas (403).
Escopos por chave: leitura, escrita, requisicoes, webhooks.
Rotação sem downtime: gere uma nova chave e a anterior permanece válida por 7 dias de carência.
Isolamento por CNPJ: a chave identifica o cliente; a API só retorna dados do próprio CNPJ.

Limites de uso

Escopo	Limite	Observação
Padrão (por chave)	60 req/min · 10.000 req/dia	Headers `X-RateLimit-*` em toda resposta
`POST /veiculos/lote`	10 req/min	Até 100 veículos por chamada (1.000/min)
`POST /requisicoes`	30 req/min	Protege contra estouro acidental de saldo

Excedeu? A API responde 429 com Retry-After. Prefira updated_since a varreduras completas.

Endpoints

Veículos (estoque completo)

Método	Rota	Descrição
GET	`/veiculos`	Lista o estoque. Filtros: `loja_id`, `status`, `placa`, `chassi`, `marca`, `ano_modelo_min/max`, `preco_min/max`, `updated_since`. Paginação por cursor (`?cursor=…&limit=100`).
POST	`/veiculos`	Cria veículo. `409` se placa/chassi já existem para o CNPJ; `422` com erros de validação campo a campo.
GET	`/veiculos/{uuid}`	Detalhe com histórico resumido de requisições RENAVE.
PATCH	`/veiculos/{uuid}`	Atualização parcial (preço, km, cor, loja, status). Placa/chassi ficam bloqueados após requisição RENAVE concluída.
DELETE	`/veiculos/{uuid}`	Baixa lógica (`status=baixado`) — o registro segue visível na sincronização incremental.
POST	`/veiculos/lote`	Upsert em lote (até 100). Casamento por chassi (prioritário) ou placa. Resposta `207 Multi-Status` item a item.

Lojas

Método	Rota	Descrição
GET	`/lojas`	Lista as lojas do cliente (filtros: `status`, `uf`, `q`).
POST	`/lojas`	Cria loja. `409` se o CNPJ da filial já existe.
PATCH	`/lojas/{id}`	Atualização parcial.
DELETE	`/lojas/{id}`	Inativação. `409` se houver veículos em estoque.

Requisições RENAVE

Método	Rota	Descrição
GET	`/requisicoes`	Histórico com filtros por tipo, status, período e `updated_since`.
POST	`/requisicoes`	Cria requisição (R$ 19,99). Header `Idempotency-Key` obrigatório — retry seguro, sem cobrança dupla. Retorna `202` e processa de forma assíncrona.
GET	`/requisicoes/{uuid}`	Status, protocolo RENAVE e detalhes de erro do SERPRO, se houver.

Webhooks e utilidades

Método	Rota	Descrição
GET	`/status`	Health check autenticado: versão, saldo e latência média do RENAVE.
POST	`/webhooks`	Cadastra webhook (URL HTTPS + eventos). O segredo HMAC é exibido uma única vez.
POST	`/webhooks/{id}/testar`	Dispara evento `ping` assinado para validar a sua verificação.
GET	`/openapi.json`	Especificação OpenAPI 3.1 pública (Swagger UI / geração de SDK).

Atualização automática (DMS ⇄ IntegraRenave)

1. Webhooks (IntegraRenave → seu sistema)

Eventos: veiculo.criado, veiculo.atualizado, veiculo.baixado, requisicao.concluida, requisicao.erro. Cada entrega leva a assinatura X-IR-Signature: t=…,v1=HMAC-SHA256(secret, t + "." + corpo) — rejeite se a diferença de tempo passar de 5 minutos (anti-replay). Retentativas: 1 min, 5 min, 30 min, 2 h, 12 h.

2. Upsert em lote (seu sistema → IntegraRenave)

POST /api/v1/veiculos/lote
X-API-Key: ir_live_SUA_CHAVE
Idempotency-Key: 7c9e6679-7425-40de-963d-df3f4b6a1e01

{
  "veiculos": [
    { "placa": "BRA2E19", "chassi": "9BWZZZ377VT004251", "renavam": "00639884962",
      "marca": "Volkswagen", "modelo": "Polo TSI", "ano_fabricacao": 2023,
      "ano_modelo": 2024, "cor": "Prata", "km": 31500, "preco": "78900.00" }
  ]
}

3. Sincronização incremental (reconciliação)

GET /api/v1/veiculos?updated_since=2026-07-10T12:00:00Z&limit=100

Guarde o maior updated_at recebido (ou o next_cursor) e repita periodicamente. Recomendação: webhooks como gatilho + updated_since como reconciliação diária. Baixas aparecem como status=baixado — nunca somem silenciosamente.

Erros padronizados (RFC 7807)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://developers.integrarenave.com.br/erros/validacao",
  "title": "Dados inválidos",
  "status": 422,
  "detail": "Um ou mais campos falharam na validação.",
  "errors": [
    { "campo": "renavam", "mensagem": "Dígito verificador não confere." },
    { "campo": "chassi", "mensagem": "As letras I, O e Q não são permitidas." }
  ]
}

Código	Quando acontece
`401`	Chave ausente, inválida, revogada ou expirada.
`402`	Saldo insuficiente para requisição RENAVE.
`403`	Escopo insuficiente ou requisição sem HTTPS.
`404`	Recurso inexistente ou de outro cliente (não vazamos existência).
`409`	Conflito: placa/chassi duplicado, chave de idempotência reutilizada com payload diferente.
`422`	Validação de campos (placa, chassi, RENAVAM, anos, valores…).
`429`	Limite de uso excedido — respeite o `Retry-After`.

Voltar ao site