Guía API

1) URL base y versión

• Base típica: https://tu-crm.nexgestion.es/api/v1
• Health check sin auth: GET /ping

Ejemplo:

curl -s https://tu-crm.nexgestion.es/api/v1/ping

2) Autenticación

Puedes usar: - Authorization: Bearer <API_KEY> - X-API-Key: <API_KEY>

Ejemplo:

curl -s https://tu-crm.nexgestion.es/api/v1/capabilities \
  -H "Authorization: Bearer crm_live_xxx"

3) Endpoints disponibles hoy

• GET /capabilities
• GET|POST|GET{id}|PUT{id}|PATCH{id} /clients
• GET|POST|GET{id}|PUT{id}|PATCH{id} /prospects
• GET|POST|GET{id}|PUT{id}|PATCH{id}|DELETE{id} /notes
• GET|POST|GET{id} /tickets
• GET|POST|GET{id}|DELETE{id}|POST{id}/test /webhooks

4) Primer flujo recomendado

1. GET /ping
2. GET /capabilities
3. POST /clients
4. GET /clients
5. PATCH /clients/{id}

5) Ejemplo crear cliente

curl -s -X POST https://tu-crm.nexgestion.es/api/v1/clients \
  -H "Authorization: Bearer crm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ana Pérez",
    "email": "[email protected]",
    "phone": "+34 600000000",
    "client_type": "persona",
    "lifecycle_stage": "cliente"
  }'

6) Errores comunes

• 401: API key inválida o ausente.
• 403: falta scope para ese endpoint.
• 422: validación de datos fallida.
• 429: rate limit alcanzado.

7) Buenas prácticas

• Reintentos con backoff para 429 y 5xx.
• Guardar id local de los recursos creados.
• Evitar enviar campos desconocidos.
• Revisar contrato OpenAPI: /api/openapi.json.