Referencia de la API

Generada desde la especificación OpenAPI que sirve la propia API, así que siempre refleja lo que está desplegado.

Descargar openapi.json

URL base — producción y pruebas

https://go-api.kroni.io/v1

El entorno lo determina el prefijo de tu llave (kg_test_ / kg_live_).

get/ping

Validar la credencial

Devuelve el entorno, la organización y los límites vigentes. Úsalo como prueba de humo al configurar la integración.

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key. invalid_api_key — La API Key no es válida.
403	app_suspended — Tu aplicación está suspendida. Escríbenos para reactivarla.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
503	api_disabled — La API de Kroni está temporalmente deshabilitada.

post/rates

Cotizar un envío

Devuelve una tarifa por servicio disponible, con el costo total real que se cobrará. El folio (`quote_id`) vive 60 minutos. `declared_value_mxn` por sí solo **no cobra nada**: viaja a la guía y sirve de base para la protección opcional, que se activa con `protect_declared_value`.

Cuerpo de la petición

Campo	Tipo	Obligatorio	Notas
`origin`	`object`	Sí	—
origin.postal_code	`string`	Sí	formato ^\d{5}$
origin.city	`string`	No	máx. 120 caracteres
origin.state

get/rates/{quote_id}

Recuperar una cotización por folio

Un folio vencido responde 200 con `expired: true`, para que puedas auditar históricos. El rechazo por vigencia ocurre al generar la guía.

Parámetros

Nombre	En	Obligatorio	Formato
`quote_id`	`ruta`	Sí	^qt_[0-9a-f]{32}$

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	quote_not_found — No encontramos esa cotización.

get/reference/carriers

Paqueterías, límites y conceptos de cargo

Describe los conceptos y cómo se calculan. Los importes concretos solo aparecen dentro de una cotización, ya sumados al precio de esa ruta.

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
503	api_disabled — La API de Kroni está temporalmente deshabilitada.

get/reference/coverage

Cobertura de un código postal

Estado, municipio y qué paqueterías cubren el código postal. Úsalo para descartar rutas sin gastar una cotización.

Parámetros

Nombre	En	Obligatorio	Formato
`postal_code`	`query`	Sí	^\d{5}$

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	no_coverage — No encontramos paqueterías con cobertura para esa ruta.

post/shipments

Generar una guía a partir de una cotización

Toma el folio (`quote_id`) y la tarifa (`rate_id`) de `POST /rates`, más las direcciones completas. Los códigos postales deben coincidir con los de la cotización. Requiere el encabezado `Idempotency-Key`. Misma llave + mismo cuerpo → la misma guía (200). Misma llave + cuerpo distinto → `409 idempotency_conflict`. En producción descuenta del saldo prepago. En pruebas no cobra ni contacta a ninguna paquetería.

Parámetros

Nombre	En	Obligatorio	Formato
Idempotency-Key	`query`	Sí	`string`

Cuerpo de la petición

Campo	Tipo	Obligatorio	Notas

get/shipments

Listar guías

Paginación por cursor: manda `next_cursor` de la respuesta anterior en `cursor`. No hay `offset`.

Parámetros

Nombre	En	Obligatorio	Formato
`limit`	`query`	No	`integer`
`cursor`	`query`	No	`string`
`status`	`query`	No	"created" \| "picked_up" \| "in_transit" \| "out_for_delivery" \| "delivered" \| "incident" \| "returned" \| "cancelled" \| "failed"

get/shipments/{shipment_id}

Consultar una guía

Parámetros

Nombre	En	Obligatorio	Formato
`shipment_id`	`ruta`	Sí	^shp_[0-9a-f]{32}$

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	shipment_not_found — No encontramos esa guía.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.

get/shipments/{shipment_id}/label

Descargar la etiqueta

Devuelve el PDF. `format=pdf` es térmica de 4×6 pulgadas (por defecto); `format=pdf_letter` es tamaño carta. Con `redirect=true` responde `302` a una URL firmada temporal, para no proxear el binario. ZPL no está disponible por ahora; pedirlo responde `415 label_format_unavailable`.

Parámetros

Nombre	En	Obligatorio	Formato
`shipment_id`	`ruta`	Sí	^shp_[0-9a-f]{32}$
`format`	`query`	No	"pdf" \| "pdf_letter"
`redirect`	`query`	No	"true" \| "false"

post/shipments/{shipment_id}/cancel

Solicitar la cancelación de una guía

NO cancela de inmediato: registra una solicitud que Kroni revisa. Solo procede mientras la paquetería no haya recolectado. Refleja `pending_review` en tu sistema hasta recibir la resolución.

Parámetros

Nombre	En	Obligatorio	Formato
`shipment_id`	`ruta`	Sí	^shp_[0-9a-f]{32}$

Cuerpo de la petición

Campo	Tipo	Obligatorio	Notas
`reason`

get/tracking/{tracking_number}

Estado de un envío

Consulta a la paquetería en tiempo real y devuelve el estado normalizado y el historial. Solo guías de tu organización.

Parámetros

Nombre	En	Obligatorio	Formato
`tracking_number`	`ruta`	Sí	`string`

Errores posibles

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	shipment_not_found — No encontramos esa guía.

Catálogo de códigos de error

Ramifica por code: es estable. El texto de message puede cambiar de redacción.

Códigos

unauthorized
invalid_api_key
key_revoked
key_expired
app_suspended
ip_not_allowed
account_blocked
wrong_environment
api_disabled
api_writes_disabled
rate_limited
validation_error
not_found
invalid_json
quote_not_found
quote_expired
rate_not_found
no_coverage
weight_limit_exceeded
dimension_limit_exceeded
multi_package_unsupported
insufficient_balance
carrier_unavailable
idempotency_conflict
idempotency_key_required
shipment_not_found
shipment_processing
shipment_cancelled
cancellation_pending
cancellation_quota_exceeded
shipment_not_cancellable
label_not_ready
label_format_unavailable
internal_error

HTTP	Códigos
400	invalid_json — El cuerpo de la petición no es JSON válido.
401	unauthorized — Falta el encabezado Authorization con tu API Key.
402	insufficient_balance — Saldo insuficiente para generar la guía.
404	quote_not_found — No encontramos esa cotización. rate_not_found — Esa tarifa no pertenece a la cotización indicada.
409	quote_expired — La cotización venció. Vuelve a cotizar antes de generar la guía. idempotency_conflict — Ya usaste esa Idempotency-Key con un cuerpo distinto. shipment_processing — La guía con esa Idempotency-Key todavía se está generando. Reintenta en unos segundos con la misma llave.
422	idempotency_key_required — Falta el encabezado Idempotency-Key. validation_error — La petición tiene campos inválidos. multi_package_unsupported — La paquetería elegida no ampara varios bultos en una sola guía.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
502	carrier_unavailable — La paquetería no respondió. Inténtalo de nuevo o elige otra tarifa.
503	api_writes_disabled — La generación de guías por API está temporalmente deshabilitada. La cotización sigue disponible.

`quote_id`	`string`	Sí	formato ^qt_[0-9a-f]{32}$
`rate_id`	`string`	Sí	formato ^rt_[0-9a-f]{12}$
`origin`	`object`	Sí	—
origin.contact_name	`string`	Sí	máx. 100 caracteres
origin.company_name	string \| null	No	—
origin.email	string \| null	No	—
origin.phone	`string`	Sí	formato ^\d{10}$
origin.street	`string`	Sí	máx. 200 caracteres
origin.street_number	`string`	Sí	máx. 20 caracteres
origin.interior_number	string \| null	No	—
origin.neighborhood	`string`	Sí	máx. 100 caracteres
origin.municipality	`string`	Sí	máx. 100 caracteres
origin.state	`string`	Sí	máx. 100 caracteres
origin.state_code	`string`	Sí	máx. 5 caracteres
origin.postal_code	`string`	Sí	formato ^\d{5}$
origin.country	`string`	Sí	máx. 2 caracteres
origin.references	string \| null	No	—
`destination`	`object`	Sí	—
destination.contact_name	`string`	Sí	máx. 100 caracteres
destination.company_name	string \| null	No	—
destination.email	string \| null	No	—
destination.phone	`string`	Sí	formato ^\d{10}$
destination.street	`string`	Sí	máx. 200 caracteres
destination.street_number	`string`	Sí	máx. 20 caracteres
destination.interior_number	string \| null	No	—
destination.neighborhood	`string`	Sí	máx. 100 caracteres
destination.municipality	`string`	Sí	máx. 100 caracteres
destination.state	`string`	Sí	máx. 100 caracteres
destination.state_code	`string`	Sí	máx. 5 caracteres
destination.postal_code	`string`	Sí	formato ^\d{5}$
destination.country	`string`	Sí	máx. 2 caracteres
destination.references	string \| null	No	—
`package`	`object`	Sí	—
package.declared_value_mxn	`number`	No	máx. 500000
package.description	string \| null	No	—
`reference`	`string`	No	máx. 120 caracteres
`label_format`	"pdf" \| "pdf_letter"	Sí	—

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
422	validation_error — La petición tiene campos inválidos.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
503	api_disabled — La API de Kroni está temporalmente deshabilitada.

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	shipment_not_found — No encontramos esa guía.
409	shipment_cancelled — Esta guía fue cancelada. label_not_ready — La etiqueta todavía se está generando. Inténtalo en unos segundos.
415	label_format_unavailable — Ese formato de etiqueta no está disponible para esta paquetería.
429	rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
503	api_disabled — La API de Kroni está temporalmente deshabilitada.

HTTP	Códigos
401	unauthorized — Falta el encabezado Authorization con tu API Key.
404	shipment_not_found — No encontramos esa guía.
409	shipment_not_cancellable — Esta guía ya no se puede cancelar. shipment_cancelled — Esta guía fue cancelada. cancellation_pending — Ya hay una solicitud de cancelación en revisión para esta guía.
422	validation_error — La petición tiene campos inválidos.
429	cancellation_quota_exceeded — Alcanzaste el máximo de solicitudes de cancelación de este mes. Escríbenos si necesitas más. rate_limited — Rebasaste el límite de peticiones. Espera unos segundos e inténtalo de nuevo.
503	api_writes_disabled — La generación de guías por API está temporalmente deshabilitada. La cotización sigue disponible.