Integração Corporativa

Integração Corporativa NetGuincho

Acione guinchos para os segurados/usuários do seu plano corporativo via APIs REST simples e seguras. Esta documentação cobre autenticação, elegibilidade, criação de chamados, gestão de segurados, relatórios de uso e webhooks.

API v1 estávelBase URL: https://api.netguincho.com.br/api/v1

Para quem é esta integração

Esta API é destinada a parceiros corporativos da NetGuincho — seguradoras, montadoras, locadoras e gestoras de frotas — que possuem contrato ativo e desejam permitir que seus segurados/usuários acionem guincho diretamente pelo app NetGuincho ou pelo portal do parceiro, com o atendimento sendo cobrado em fatura mensal B2B.

Como funciona em 3 passos

Cadastre seus segurados. Use o endpoint /insurer-portal/customers para vincular CPFs ao seu contrato e definir limites mensais por segurado.
Verifique elegibilidade no ato do acionamento. Antes de exibir o formulário de chamado, chame /insurer-portal/eligibility/check com o CPF do segurado.
Receba eventos por webhook. Configure uma URL de webhook para ser notificado em tempo real sobre criação, despacho, conclusão e cancelamento dos chamados.

Atalhos

Autenticação

API Key (X-API-Key) para backend e JWT do segurado para apps.

Abrir

Elegibilidade

Verifique antes de exibir o formulário de solicitação.

Abrir

Segurados

CRUD de segurados, limites mensais e status.

Abrir

Webhooks

Eventos em tempo real com retry e assinatura HMAC.

Abrir

Quickstart — Acionar guincho via API

O exemplo abaixo verifica a elegibilidade do segurado e, se ele estiver habilitado, retorna a quantidade de acionamentos restantes no mês.

cURL

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

JSON

{
  "eligible": true,
  "insurer_id": "9b3f...",
  "insurer_customer_id": "2a1c...",
  "monthly_limit": 3,
  "usage_this_month": 1,
  "remaining": 2
}

Pré-requisitos

Contrato corporativo ativo com a NetGuincho.
API Key emitida pelo time de operações (header X-API-Key).
(Opcional) URL pública para receber webhooks com TLS válido.
Sua aplicação cliente (web ou mobile) capaz de obter o CPF do segurado para iniciar o fluxo.

Fluxo de ponta a ponta

1
Segurado abre o app/portal
Login por CPF + senha (ou token enviado por email).
2
Validação de elegibilidade
Contrato ativo + segurado vinculado + cota mensal disponível.
3
Solicitação de serviço
Localização + tipo de ocorrência (guincho, bateria, pneu, combustível).
4
Despacho automático
NetGuincho localiza prestador disponível e envia push ao guincheiro.
5
Aceite e atendimento
Prestador aceita o chamado; segurado acompanha em tempo real.
6
Encerramento
Operação finalizada. Acionamento deduzido do limite mensal.
7
Faturamento mensal
Consolidação automática em fatura B2B enviada ao corporativo.

Convenções da API

Formato de payload: application/json codificado em UTF-8.
IDs são UUID v4 em todas as entidades.
Datas em ISO 8601 (UTC), formato YYYY-MM-DDTHH:mm:ss.sssZ.
CPF aceito apenas com 11 dígitos, sem máscara.
Códigos HTTP padrão: 2xx sucesso, 4xx erro do cliente, 5xx erro interno.
Respostas de erro sempre incluem error_code e message.