Integração Corporativa

Checagem de elegibilidade

Verifique se um segurado pode acionar o guincho antes de exibir o formulário de solicitação. Ideal para evitar fricção quando o segurado não está habilitado.

POST/api/v1/insurer-portal/eligibility/check

10 req/min por CPFX-API-Key

Quando chamar

Imediatamente após o segurado abrir a tela de "Solicitar guincho".
Antes de processar qualquer formulário de criação de chamado em sua aplicação.
Como verificação periódica em dashboards do segurado.

Parâmetros

Campo	Tipo	Descrição
`cpf`obrigatório	`string (11 dígitos)`	CPF do segurado, apenas dígitos, sem máscara.

Exemplo de requisição

cURL

curl -X POST 'https://api.netguincho.com.br/api/v1/insurer-portal/eligibility/check' \
  -H 'X-API-Key: live_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{ "cpf": "12345678900" }'

Resposta de sucesso (200)

JSON

{
  "eligible": true,
  "insurer_id": "9b3f8a12-1234-4abc-9def-0123456789ab",
  "insurer_customer_id": "2a1c4f67-89ab-4cde-9876-543210fedcba",
  "monthly_limit": 3,
  "usage_this_month": 1,
  "remaining": 2
}

Respostas de erro

O endpoint retorna sempre um JSON com eligible: false, error_code e message pronta para exibir ao segurado.

HTTP	error_code	Significado
403	CONTRACT_INACTIVE	Contrato corporativo inativo, suspenso ou expirado.
404	USER_NOT_FOUND	CPF informado não está vinculado ao seu contrato.
403	USER_INACTIVE	Segurado existe mas está desativado pelo corporativo.
429	LIMIT_EXCEEDED	Limite mensal de acionamentos atingido para este segurado.

JSON

{
  "eligible": false,
  "error_code": "LIMIT_EXCEEDED",
  "message": "Você atingiu o limite de acionamentos deste mês."
}

Rate limiting

Para evitar varredura de CPFs, este endpoint tem limite de 10 requisições por minuto por CPF. Em caso de excesso a API responde com 429 Too Many Requests e o header Retry-After indicando quantos segundos aguardar.