OpenAPI e Postman

A especificação OpenAPI 3.0 e a coleção Postman, geradas do catálogo vigente.

A especificação OpenAPI e a coleção Postman são geradas pelo backend a partir do catálogo vigente: serviço novo, campo novo e código de erro novo aparecem nelas sem edição manual. São públicas (não exigem chave).

openapi.jsonOpenAPI 3.0.3, versão 1.1.0: 13 operações, 29 objetos e 8 eventos de webhook. postman-collection.jsonColeção Postman com as mesmas rotas, com a chave na variável api_key. api-errosCatálogo de códigos de erro em JSON (http, codigo, retryable, descricao).

Gerar um cliente tipado

A especificação declara o corpo de cada resposta, os enums e os campos obrigatórios: dá para gerar SDK em TypeScript, Python, PHP, Java ou C# com as ferramentas padrão.

bashtipos TypeScript a partir do contrato

npx openapi-typescript https://api.zapcarconsulta.com.br/public/openapi.json -o zapcar-api.d.ts

bashvalidar o contrato

npx @redocly/cli lint https://api.zapcarconsulta.com.br/public/openapi.json

Os eventos de webhook estão em x-webhooks (convenção do Redoc), cada um com os cabeçalhos X-ZapCar-* e o corpo WebhookPayload.

Testar no Postman

Passo 1: Importe a coleção
No Postman, Import → Link → cole https://api.zapcarconsulta.com.br/public/postman-collection.json.
Passo 2: Configure a chave
Na coleção, aba Variables, preencha api_key com a sua chave. Comece pela de teste (zc_test_…).
Passo 3: Teste a conexão
Rode GET /v1/servicos. Resposta 200 confirma chave e conexão.
Passo 4: Crie e acompanhe uma consulta
POST /v1/consultas com { "servico": "consulta", "placa": "TST0001" }, cole o id da resposta na variável id e rode GET /v1/consultas/:id até concluido.

O erro mais comum no Postman é deixar o método em POST e colocar o id na URL. Para ver um resultado é GET com id; para criar é POST sem id.

O que o contrato descreve

Fonte desta página: especificação lida agora da API, servidor https://api.zapcarconsulta.com.br.

Método	Caminho	operationId
GET	`/v1/servicos`	`listarServicos`
GET	`/v1/saldo`	`consultarSaldo`
POST	`/v1/consultas`	`criarConsulta`
GET	`/v1/consultas/{id}`	`statusConsulta`
GET	`/v1/consultas/{id}/pdf`	`baixarPdf`
GET	`/v1/consultas/{id}/imagens/{tipo}/{indice}`	`baixarImagem`
POST	`/v1/fipe`	`consultarFipe`
GET	`/v1/fipe/tabela/referencias`	`listarReferenciasFipe`
GET	`/v1/fipe/tabela/{tipo}/marcas`	`listarMarcasFipe`
GET	`/v1/fipe/tabela/{tipo}/marcas/{marca}/modelos`	`listarModelosFipe`
GET	`/v1/fipe/tabela/{tipo}/marcas/{marca}/modelos/{modelo}/anos`	`listarAnosFipe`
GET	`/v1/fipe/tabela/{tipo}/codigo/{codigo_fipe}/anos`	`listarAnosPorCodigoFipe`
POST	`/v1/fipe/tabela`	`consultarFipeTabela`

Encontrou divergência?

Se a API responder diferente do que a especificação ou esta documentação dizem, a especificação vale como contrato e a diferença é defeito nosso. Avise a equipe de integração com o request_id da resposta.