> For the complete documentation index, see [llms.txt](https://docs.zipnova.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipnova.com/carriers/flujo-de-integracion.md).

# Flujo de integración

El recorrido completo para operar tu propio transporte en Zipnova Envíos, de punta a punta.

Opera tu propio transporte en Zipnova Envíos y llega a más sellers, sin integraciones a medida. Desde el Carrier Hub creas tus Carriers y, por API, cotizas, recibes envíos, cargas etiquetas e informas tracking y estados.

Esta página explica el recorrido completo. Cada paso enlaza a su detalle.

## Qué puedes hacer

* **Crear varios Carriers** desde el Carrier Hub. Cada uno tiene sus propias credenciales, tarifarios, integración y configuración.
* **Cotizar** con un tarifario fijo o con un callback a tu API.
* **Operar los envíos**: recibir notificaciones, consultar el detalle, subir etiquetas e informar tracking y estados estandarizados.
* **Elegir quién te usa**: mantener tu Carrier privado, dentro de tu Organization, o publicarlo para otras cuentas con una [modalidad de acceso](/carriers/visibilidad-y-modalidades-de-acceso.md).
* **Usar Zipnova Rutas** como integración plug & play, si ya operas con él.

## Quién interviene

En una integración propia (`custom`), tu Carrier y Zipnova se llaman en las dos direcciones:

```mermaid
sequenceDiagram
    participant S as Seller
    participant Z as Zipnova
    participant C as Tu Carrier
    S->>Z: Cotiza un envío
    Z->>C: Callback de cotización (si cotizas por API)
    C-->>Z: Precio y plazo
    Z-->>S: Ofertas de los Carriers
    S->>Z: Contrata tu Carrier
    Z->>C: Notificación new
    C->>Z: Consulta el envío y sube la etiqueta
    Z->>C: Notificación ready_to_ship
    C->>Z: Informa tracking y estados
    Z-->>S: Seguimiento del envío
```

Si es la primera vez que integras un transporte con Zipnova, empieza por [Conceptos clave](/carriers/conceptos-clave.md).

## Antes de empezar

* Tu Organization tiene que estar habilitada por Zipnova para crear Carriers.
* Define tu modelo de integración:
  * **Integración propia por API** (`custom`) o con [Zipnova Rutas](/carriers/integracion-con-zipnova-rutas.md) (`zipnova_routes`).
  * **Tarifario fijo** o **callback a tu API** para cotizar. Ver [Cómo se cotiza](/carriers/como-se-cotiza.md).
  * **Carrier privado o público**, y en ese caso con qué modalidad de acceso.

## Paso a paso

{% stepper %}
{% step %}

### Crea tu Carrier en el Carrier Hub

Elige el nombre, la integración (`custom` o `zipnova_routes`), la visibilidad y, si es público, la modalidad de acceso. Una Organization puede tener varios Carriers y cada uno se administra de forma independiente.
{% endstep %}

{% step %}

### Obtén tus credenciales

Cada Carrier tiene una **API key**, con la que llamas a la API de Zipnova, y un **`hmac_secret`**, con el que validas las llamadas que Zipnova hace a tu Carrier. Comprueba que la API key funciona con `GET /me`. Ver [Convenciones y errores](/carriers/referencia-api/convenciones-y-errores.md) y [Validar la firma de Zipnova](/carriers/endpoints/validar-la-firma-de-zipnova.md).
{% endstep %}

{% step %}

### Registra tus URLs

En una integración `custom`, configura la URL que recibe las [notificaciones de envíos](/carriers/endpoints/notificaciones-de-envios.md) y, si cotizas por API, la URL del [callback de cotización](/carriers/endpoints/cotizacion.md). Zipnova las valida al guardarlas y firma cada llamada.
{% endstep %}

{% step %}

### Carga tus tarifarios

Crea cada tarifario con `POST /tariffs`, publica sus zonas con `PUT /tariffs/{tariff_id}/rates` y actívalo. Si cotizas por API, mantén zonas publicadas como respaldo. Ver [Cómo se cotiza](/carriers/como-se-cotiza.md) y [Tarifarios](/carriers/referencia-api/tarifarios.md).
{% endstep %}

{% step %}

### Opera los envíos

Cuando un seller contrata tu Carrier, recibes la notificación `new`, consultas el envío, subes la etiqueta, informas el tracking y vas reportando los estados hasta la entrega. Ver [Ciclo de vida de un envío](/carriers/ciclo-de-vida-de-un-envio.md) y [Envíos](/carriers/referencia-api/envios.md).
{% endstep %}

{% step %}

### Certifica y sal a producción

Si publicas tu Carrier en el Marketplace, Zipnova lo certifica: revisa los webhooks y un flujo end-to-end con datos de prueba. Puedes ver el resultado en `certification_status` de `GET /me`. Ver [Visibilidad y modalidades de acceso](/carriers/visibilidad-y-modalidades-de-acceso.md).
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Si tu Carrier opera con Zipnova Rutas, no necesitas implementar webhooks ni subir etiquetas. Ver [Integración con Zipnova Rutas](/carriers/integracion-con-zipnova-rutas.md).
{% endhint %}

## Checklist antes de salir a producción

* [ ] `GET /me` responde con la API key de tu Carrier.
* [ ] Validas la firma HMAC de cada llamada de Zipnova y rechazas timestamps con más de 5 minutos de diferencia.
* [ ] Tu URL de notificaciones responde `2xx` rápido y procesa cada evento de forma idempotente.
* [ ] Si cotizas por API, tu callback responde en menos de 500 ms y tienes un tarifario fijo de respaldo.
* [ ] Tus tarifarios están activos y con las zonas publicadas.
* [ ] Subes la etiqueta en PDF 10x15, con una página por bulto.
* [ ] Informas el tracking y los estados, sabiendo que los estados finales no se pueden modificar.

## Dónde seguir

* [Conceptos clave](/carriers/conceptos-clave.md): las piezas y los términos de la integración.
* [Visibilidad y modalidades de acceso](/carriers/visibilidad-y-modalidades-de-acceso.md): quién puede usar tu Carrier.
* [Cómo se cotiza](/carriers/como-se-cotiza.md): tarifario fijo, callback y fallback.
* [Ciclo de vida de un envío](/carriers/ciclo-de-vida-de-un-envio.md): qué informar en cada paso.
* [Integración con Zipnova Rutas](/carriers/integracion-con-zipnova-rutas.md): la alternativa plug & play.
* [Referencia de la API](/carriers/referencia-api/convenciones-y-errores.md): servidores, autenticación, tarifarios y envíos.