Integra tus solicitudes con Altyro.

Seguridad

Autenticación

Las integraciones de servidor envían X-API-Key. El portal Altyro usa Authorization: Bearer <Firebase ID token> y su empresa autorizada. Nunca incluyas una clave de integración en código de navegador ni en la URL.

URLs base

Dos entornos, una integración

La API de producción responde en el dominio de Firebase Hosting indicado abajo. Los ejemplos copiables usan producción y requieren autorización para un piloto; el sandbox aislado todavía no está disponible.

Referencia de entrada

Qué enviar al crear

El cuerpo de POST /v1/solicitudes es un objeto JSON. En un lote, cada elemento de rows usa los mismos campos. Envía los nombres exactamente como aparecen aquí.

Desliza las tablas hacia los lados para ver todas las columnas.

Solicitud y dirección

Dentro de ubicacionCoordenadas, lat y lng deben ser números JSON (sin comillas). Latitud: −90 a 90. Longitud: −180 a 180. Si se envía el objeto, ambos valores son obligatorios; un punto inválido devuelve 400 COORDINATES_INVALID. La calle y comuna siguen siendo necesarias aunque envíes el punto.

Receptor

Paquete y datos propios

No envíes una tarifa calculada: Altyro determina el total desde la empresa, la sucursal, la comuna, el tamaño y el horario.

Valores que debes evitar

Paso 1 · creación individual

Crear una solicitud

Envía POST /v1/solicitudes con Content-Type: application/json, tu clave y una Idempotency-Key de 8 a 180 caracteres. Guarda el solicitudId para consultas privadas y el codigo para seguimiento.

curl -X POST https://altyro-api.web.app/v1/solicitudes \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: TU_CLAVE_DE_PRODUCCION' \
  -H 'Idempotency-Key: pedido-1042' \
  -d '{
    "idSucursal": "SUCURSAL_ID",
    "tipo": "envio",
    "fechaRetiro": "2026-09-25",
    "calle": "Avenida Providencia",
    "nCalle": "1208",
    "comuna": "Providencia",
    "receptorNombre": "Cliente de prueba",
    "receptorTelefono": "+56912345678",
    "receptorCorreo": "[email protected]",
    "tamanio": "m",
    "codigoReferencia": "PED-1042",
    "notas": "Entregar en conserjería",
    "ubicacionCoordenadas": { "lat": -33.4372, "lng": -70.6506 }
  }'

{
  "requestId": "7e2a2f4d-54c8-4d72-b3a4-34723658482b",
  "rowId": "api-fila-generada",
  "status": "created",
  "solicitudId": "SOLICITUD_ID",
  "codigo": "a12b34c56d78e90fa12b34c56d78e90f",
  "total": 4990
}

La respuesta real puede incluir más campos. created indica una solicitud nueva; existing indica que esa misma intención ya tenía una solicitud; review_pending indica que quedó agendada con revisión de dirección; failed incluye un objeto error. Reutiliza la misma Idempotency-Key al reintentar. Una clave distinta representa otra intención, aunque el JSON sea igual.

Paso 1 · creación por lote

Crear varias solicitudes

POST /v1/solicitudes/lotes recibe un objeto con rows, entre 1 y 100 solicitudes. Cada fila tiene los campos de la tabla anterior y un rowId único dentro del lote. La respuesta trae un resultado independiente por fila; un fallo no oculta las filas creadas.

curl -X POST https://altyro-api.web.app/v1/solicitudes/lotes \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: TU_CLAVE_DE_PRODUCCION' \
  -H 'Idempotency-Key: lote-2026-09-25-01' \
  -d '{
    "rows": [
      {
        "rowId": "pedido-1042",
        "idSucursal": "SUCURSAL_ID",
        "tipo": "envio",
        "fechaRetiro": "2026-09-25",
        "calle": "Avenida Providencia",
        "nCalle": "1208",
        "comuna": "Providencia",
        "receptorNombre": "Ana Pérez",
        "receptorTelefono": "+56912345678",
        "tamanio": "m"
      },
      {
        "rowId": "pedido-1043",
        "idSucursal": "SUCURSAL_ID",
        "tipo": "cambio",
        "fechaRetiro": "2026-09-25",
        "calle": "Los Leones",
        "nCalle": "250",
        "comuna": "Providencia",
        "receptorNombre": "Luis Díaz",
        "receptorTelefono": "+56987654321",
        "receptorCorreo": "correo-invalido",
        "tamanio": "s"
      }
    ]
  }'

{
  "created": 1,
  "existing": 0,
  "pendingReview": 0,
  "failed": 1,
  "results": [
    { "rowId": "pedido-1042", "status": "created", "solicitudId": "SOLICITUD_1", "codigo": "CODIGO_1" },
    { "rowId": "pedido-1043", "status": "failed", "error": { "code": "ROW_INVALID", "message": "La solicitud normalizada no es valida.", "details": [{ "field": "receptorCorreo", "message": "Correo receptor invalido." }] } }
  ]
}

El lote es síncrono: usa un timeout de cliente de al menos 180 segundos. Si una falla temporal del proveedor de geocodificación deja el lote parcial, reintenta con la misma clave y el mismo contenido. Una fila creada antes puede regresar como existing; concilia por rowId y no sumes el total de distintos intentos.

Paso 2 · consulta privada

Estado e hitos de tus solicitudes

La clave solo puede leer solicitudes de su empresa. Usa la lista para localizar un pedido y GET /v1/solicitudes/{id} para ver su estado actual y la secuencia de hitos. {id} es el solicitudId devuelto al crear, no el código público.

Listar y filtrar

Usa como máximo uno de estado, referencia o codigo por consulta. Los resultados se ordenan por fecha de creación, del más reciente al más antiguo.

curl 'https://altyro-api.web.app/v1/solicitudes?referencia=PED-1042&limit=30' \
  -H 'X-API-Key: TU_CLAVE_DE_PRODUCCION'

{
  "items": [
    {
      "id": "SOLICITUD_ID",
      "codigo": "a12b34c56d78e90fa12b34c56d78e90f",
      "referencia": "PED-1042",
      "tipo": "envio",
      "estado": "retiroPendiente",
      "fechaCreacion": "2026-09-23T16:15:00.000Z",
      "fechaRetiro": "2026-09-25"
    }
  ],
  "nextCursor": null,
  "requestId": "6a885909-6025-47c1-9203-28652e676774"
}

Abrir el detalle y leer hitos

curl 'https://altyro-api.web.app/v1/solicitudes/SOLICITUD_ID' \
  -H 'X-API-Key: TU_CLAVE_DE_PRODUCCION'

{
  "id": "SOLICITUD_ID",
  "codigo": "a12b34c56d78e90fa12b34c56d78e90f",
  "referencia": "PED-1042",
  "tipo": "envio",
  "estado": "enRuta",
  "fechaCreacion": "2026-09-23T16:15:00.000Z",
  "fechaRetiro": "2026-09-25",
  "hitos": [
    { "estado": "creado", "fecha": "2026-09-23T16:15:00.000Z", "imagenes": [] },
    { "estado": "enRuta", "fecha": "2026-09-25T13:20:00.000Z", "imagenes": [] }
  ],
  "requestId": "9df5c209-2a1d-42cb-86bd-d5fb3d031668"
}

estado es la situación actual. hitos registra pasos con su fecha ISO 8601, que puede ser null en un paso inferido. Los estados habituales incluyen creado, retiroPendiente, retirado, enRuta, entregado, fallido y devolucion. También pueden aparecer estados de revisión u otros estados operativos; conserva el valor recibido.

Paso 3 · consulta pública

Seguimiento por código

GET /v1/seguimiento/{codigo} usa el codigo generado por Altyro. No necesita clave. Entrega estado, fechas y nombres de hitos; no entrega dirección, contactos, comentarios, fotos ni coordenadas. Puede consultar códigos anteriores a la API.

curl 'https://altyro-api.web.app/v1/seguimiento/a12b34c56d78e90fa12b34c56d78e90f'

{
  "codigo": "a12b34c56d78e90fa12b34c56d78e90f",
  "estado": "enRuta",
  "fechaCreacion": "2026-09-23T16:15:00.000Z",
  "fechaRetiro": "2026-09-25",
  "hitos": [
    { "estado": "creado", "fecha": "2026-09-23T16:15:00.000Z" },
    { "estado": "enRuta", "fecha": "2026-09-25T13:20:00.000Z" }
  ],
  "requestId": "89417e77-efb9-4f23-a9e0-54164a9ab07b"
}

Si necesitas la referencia, el tipo o fotos de una solicitud de tu empresa, usa el detalle privado con tu clave. Para integrar una página pública, usa el código y muestra el próximo hito cuando exista; no supongas que siempre habrá una fecha para cada paso.

Evidencia privada

Fotos de los hitos

El detalle autenticado puede incluir imagenes en cada hito. Cada elemento tiene url y expiresAt; la URL temporal vence a los 10 minutos. Para renovarla, envía la URL anterior o la clave de esa foto a POST /v1/solicitudes/{id}/fotos/firmar. La foto debe pertenecer a esa solicitud y empresa.

curl -X POST 'https://altyro-api.web.app/v1/solicitudes/SOLICITUD_ID/fotos/firmar' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: TU_CLAVE_DE_PRODUCCION' \
  -d '{ "url": "URL_ANTERIOR_DEL_HITO" }'

La respuesta devuelve una nueva url, su expiresAt y requestId. El seguimiento público nunca entrega fotos.

Operación

Errores, límites y reintentos

Los errores generales incluyen code, message y requestId. Guarda requestId para soporte. En la creación por lote, revisa también el status y error de cada fila aunque la petición responda HTTP 200.

Estos límites son orientativos en la vista previa local; la protección de borde se configurará antes de habilitar el servicio público.