Introducción a la API de GRIP

Esta guía está dirigida a desarrolladores que quieran integrarse con GRIP mediante su API REST. A través de ella podés crear y actualizar expediciones, consultarlas, conocer los conductores disponibles y obtener las reglas de recurrencia, sin necesidad de operar desde el back office.

Si todavía no conocés la aplicación, te recomendamos leer primero la documentación general de GRIP, donde se explican los conceptos de expedición, cliente, agencia, conductor, tipo de servicio y tarifa que se usan a lo largo de esta referencia.

Conceptos básicos

Expedición (o servicio): es la unidad de trabajo principal de GRIP. Representa una entrega o recogida con su origen, destino, contacto, paquetes, horarios y estado. En la API los endpoints de expediciones viven bajo la ruta /services.
Referencia (reference): identificador que vos asignás a cada expedición. Es la forma habitual de localizar una expedición desde la API.
Dominio (Authorization-Domain): identifica tu cuenta/entorno dentro de GRIP. Los identificadores internos que devuelve la API vienen prefijados con el dominio (por ejemplo dev_113453).

URL base

Todas las peticiones se realizan sobre la versión 2 de la API:

https://api.app.vonzu.es/api/v2

A partir de esta base se construyen las rutas de cada recurso, por ejemplo https://api.app.vonzu.es/api/v2/services/create.

Autenticación

La API se autentica mediante dos cabeceras (headers) que debés enviar en todas las peticiones:

Cabecera	Obligatoria	Descripción
`secret-api-key`	Sí	Tu clave de API secreta. Identifica y autoriza a tu integración.
`Authorization-Domain`	Sí	El dominio (cuenta/entorno) sobre el que operás.
`Content-Type`	Sí (en POST)	Debe ser `application/json`.

Importante: la secret-api-key es una credencial sensible. No la incluyas en código de cliente (frontend), repositorios públicos ni URLs. Guardala en variables de entorno o en un gestor de secretos. Si creés que se ha filtrado, contactá con el equipo de GRIP para rotarla.

Ejemplo de cabeceras

secret-api-key: TU_API_KEY
Authorization-Domain: TU_DOMINIO
Content-Type: application/json

Ejemplo de petición autenticada (cURL)

curl --location 'https://api.app.vonzu.es/api/v2/services/findByReference' \
  --header 'secret-api-key: TU_API_KEY' \
  --header 'Authorization-Domain: TU_DOMINIO' \
  --header 'Content-Type: application/json' \
  --data '{
    "find": { "reference": "MI-REFERENCIA-001" }
  }'

Formato de las peticiones y respuestas

El cuerpo (body) de las peticiones POST se envía siempre en JSON.
Las respuestas se devuelven en JSON con codificación UTF-8.
Las fechas se expresan en formato YYYY-MM-DD (por ejemplo 2023-07-05) y las marcas de tiempo completas en ISO 8601 (por ejemplo 2022-12-05T16:35:17.222Z).
Los horarios de las franjas (schedules) se expresan como pares HH:MM:SS.
Las coordenadas geográficas siguen el formato GeoJSON[longitud, latitud] (en ese orden).

Resumen de endpoints

Recurso	Método	Ruta	Descripción
Crear expedición	`POST`	`/services/create`	Crea una nueva expedición.
Actualizar expedición	`POST`	`/services/update`	Modifica una expedición existente.
Buscar por referencia	`POST`	`/services/findByReference`	Devuelve una expedición a partir de su referencia.
Buscar	`POST`	`/services/find`	Devuelve una expedición a partir de un criterio.
Buscar varias	`POST`	`/services/findMany`	Busca múltiples expediciones con filtros avanzados.
Conductores libres	`GET`	`/drivers`	Lista conductores disponibles cerca de una ubicación.
Ubicación de conductor	`GET`	`/drivers/location`	Devuelve la última ubicación del conductor de una expedición.
Reglas recurrentes	`GET`	`/recurrentRules`	Devuelve la regla de recurrencia de una expedición.

En los siguientes artículos se detalla cada endpoint con sus parámetros, ejemplos de petición y de respuesta.