Getting started

Visão geral

A API de integração permite que sistemas externos operem sobre a rede do representante autenticado pela chave de API.

Item	Valor
Base path	/api/v1/integracao
Autenticação	Header X-API-Key
Spec OpenAPI	/v3/api-docs/integracao

1. Obter uma API key

1. Acesse o painel do representante no QuickPass.
2. Abra API de integração.
3. Gere uma chave com um nome descritivo (ex.: ERP Produção).
4. Copie a chave imediatamente — o valor completo só é exibido uma vez.

O link do painel pode ser configurado por ambiente (panelUrl em config.js). Em produção costuma ser o app QuickPass em /representative/integracao-api.

2. Autenticar as requisições

Envie a chave em todas as chamadas:

GET /api/v1/integracao/produtores?page=0&size=20
X-API-Key: qp_sua_chave_aqui
Accept: application/json

Exemplo com curl:

curl -sS \
  -H "X-API-Key: $QUICKPASS_API_KEY" \
  -H "Accept: application/json" \
  "$API_BASE/api/v1/integracao/produtores?page=0&size=20"

A chave identifica o representante e restringe o acesso aos produtores da sua rede.

3. Base URL

Ambiente	Base URL
Homologação	https://staging.api.quickpass.com.br
Produção	https://api.quickpass.com.br

Prefixe as rotas com /api/v1/integracao (ex.: https://staging.api.quickpass.com.br/api/v1/integracao/produtores).

Na referência da API (Scalar, página separada) os servers são Homologação e Produção — não há localhost.

4. Erros comuns

Situação	HTTP	O que fazer
Chave ausente ou inválida	401	Verifique o header X-API-Key
Produtor fora da rede	403 / 404	Use apenas IDs retornados pela listagem
Payload inválido	400	Confira campos obrigatórios na referência
Rate limit	429	Aguarde e retente com backoff

Próximos passos

1. Visão da seção Representantes
2. Cadastrar / listar produtores
3. Explorar a referência da API — autenticação com X-API-Key; ambiente padrão Homologação (dá para trocar para Produção)