Integração Corporativa

Autenticação

A API NetGuincho aceita dois mecanismos de autenticação. Use API Key para integrações backend-to-backend e JWT para apps de segurado.

1. API Key (recomendado para backend)

Cada parceiro corporativo recebe uma API Key única. Envie-a no header X-API-Key em todas as requisições aos endpoints /insurer-portal/*.

cURL

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

Estrutura da chave

A chave segue o formato:

Shell

<environment>_sk_<random_secret>

# Exemplos:
live_sk_d8f3a91c0b7e4f6a82d104c5e3b7a9f0
test_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Rotação de chaves

Você pode manter até 2 chaves ativas simultaneamente para permitir rotação sem downtime. O processo recomendado:

Gere uma nova chave pelo painel administrativo.
Atualize sua aplicação para usar a nova chave.
Após confirmar funcionamento, revogue a chave antiga.

2. JWT do segurado (apps cliente)

Quando o próprio segurado aciona o serviço pelo app NetGuincho ou pelo portal do parceiro, a autenticação é feita por JWT obtido no login. O JWT contém um claim adicional corporateContext com o vínculo ao seu contrato.

POST/api/v1/auth/login

cURL

curl -X POST 'https://api.netguincho.com.br/api/v1/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier": "12345678900",
    "password": "<senha-do-segurado>"
  }'

A resposta inclui o JWT e os dados do usuário:

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "8f3e...",
    "fullName": "João da Silva",
    "userType": "cliente",
    "corporateContext": {
      "insurerId": "9b3f...",
      "insurerCustomerId": "2a1c..."
    }
  }
}

Use o token nas chamadas subsequentes:

cURL

curl 'https://api.netguincho.com.br/api/v1/service-requests' \
  -X POST \
  -H 'Authorization: Bearer eyJhbGc...' \
  -H 'Content-Type: application/json' \
  -d '{ "location": { "lat": -23.561, "lng": -46.656 }, "occurrenceType": "battery" }'

Erros de autenticação

JSON

{
  "statusCode": 401,
  "error_code": "INVALID_API_KEY",
  "message": "API Key inválida ou expirada"
}