Referencia REST v1

Los recursos mantienen la misma forma lógica en TEST y LIVE. Los permisos se asignan por credencial.

GET/health

Estado del servicio. No requiere credencial.

GET/schema.json

Especificación JSON pública de la API. No requiere credencial.

POST/shipments/quote

Valida datos y devuelve una cotización.

Permiso: shipments:quote

GET/shipments

Lista envíos de la empresa autenticada.

Permiso: shipments:read

POST/shipments

Crea un envío. Requiere Idempotency-Key.

Permiso: shipments:create

GET/shipments/{shipment_number}

Consulta un envío específico.

Permiso: shipments:read

POST/shipments/{shipment_number}/cancel

Solicita cancelación bajo las reglas operativas vigentes.

Permiso: shipments:cancel

GET/tracking/{shipment_number}

Consulta estado y eventos.

Permiso: tracking:read

POST/sandbox/shipments/{shipment_number}

Solo TEST. Simula un cambio de estado en un envío de prueba.

Permiso: shipments:create

Ejemplo de creación

{
    "recipient": {
        "name": "Cliente Demo",
        "phone": "55555555",
        "address": "10 avenida 1-20",
        "zone": "10",
        "municipality": "Guatemala",
        "reference": "Portón negro"
    },
    "pickup": {
        "address": "Sucursal principal",
        "municipality": "San Marcos"
    },
    "package": {
        "content": "Pedido e-commerce",
        "pieces": 1,
        "weight_lbs": "2.00"
    },
    "cod": {
        "amount": "125.00"
    }
}

Respuesta TEST

{
    "shipment_number": "ARI-260901-ABC123",
    "status": "created",
    "environment": "test",
    "simulated": true,
    "request_id": "req_..."
}

Errores

HTTPCódigoSignificado

400invalid_json / idempotency_key_requiredSolicitud incompleta o JSON inválido.

401unauthorizedCredencial inválida, revocada o del ambiente equivocado.

403forbiddenLa credencial no tiene el permiso requerido.

404not_foundEl recurso no existe para la empresa autenticada.

409operation_conflictLa operación entra en conflicto con el estado actual.

422validation_errorLos datos no cumplen las reglas del recurso.

429rate_limit_exceededSe excedió temporalmente el límite de solicitudes.

500internal_errorError interno sanitizado. Usa request_id al contactar soporte.

Permisos disponibles

shipments:quote
shipments:create
shipments:read
shipments:cancel
tracking:read
webhooks:manage

Descargar especificación JSON