REFERENCIA DE LA API
Un contrato claro.
Una integración predecible.
JSON sobre HTTPS. Credenciales por integración y solicitudes que sobreviven a un reintento.
01Autenticación e idempotencia
Envía la credencial exclusivamente desde el servidor de tu aplicación, en Authorization: Bearer <CREDENCIAL>. Nunca la incluyas en URLs, repositorios o código distribuido al navegador.
Para crear una solicitud o inactivar una versión agrega Idempotency-Key: de 8 a 100 caracteres alfanuméricos, punto, guion, dos puntos o guion bajo. La misma clave y los mismos datos normalizados devuelven la solicitud original. Otros datos con la misma clave producen 409.
La referencia comercial se configura para tu credencial. El integrador no envía precios, servidor, códigos de cliente, SSID ni contraseñas.
02Datos mínimos
Todos los campos se envían como texto. Se rechazan campos desconocidos, valores nulos y caracteres de control. Cuerpo máximo: 16 KiB en UTF-8. En esta etapa, Chile es el único país con validador implementado; su disponibilidad requiere habilitación y catálogo.
03Endpoints
POST/api/v1/versiones202
Recibe la solicitud y devuelve solicitudId, estado, testing, recibidaEnUtc, repetida y estadoUrl. Conserva el identificador. Las cabeceras Location y Retry-After indican dónde y cuándo consultar.
{
"solicitudId": "00000000-0000-4000-8000-000000000001",
"estado": "pendiente_aprovisionamiento",
"testing": "sin_crear",
"recibidaEnUtc": "2026-11-10T12:00:00.000Z",
"repetida": false,
"estadoUrl": "/api/v1/solicitudes/00000000-0000-4000-8000-000000000001",
"mensaje": "Solicitud recibida. El aprovisionamiento todavía no está habilitado."
}
GET/api/v1/solicitudes/{solicitudId}200
Datos y eventos de una solicitud propia. Un identificador ajeno devuelve 404.
GET/api/v1/solicitudes?offset=0&limit=20200
Lista solo tus solicitudes, ordenadas por recepción. Devuelve solicitudes, offset, limit y hasMore.
GET/api/v1/catalogos/paises200
Devuelve paises con codigo, nombre, validacion y permiteSolicitarVersion. Consultar un catálogo no habilita por sí solo la creación de versiones.
GET/api/v1/catalogos/comunas?pais=CL&offset=0&limit=50200
Devuelve comunas, offset, limit y hasMore. Admite buscar de hasta 60 caracteres. El límite máximo es 100; consulta los bloques siguientes mientras hasMore sea verdadero.
GET/api/v1/integracion200
Identidad, referencia comercial, vencimiento, límite de solicitudes por minuto y países habilitados. No devuelve la credencial.
04Inactivar una versión
POST/api/v1/versiones/inactivar200
Envía Authorization: Bearer, Content-Type: application/json e Idempotency-Key. La credencial debe tener permiso explícito para el SSID. Conocer el identificador no concede acceso.
{
"ssid": "<SSID>",
"motivo": "Suspensión solicitada por el cliente."
}
ssid: texto de 1 a 20 caracteres alfanuméricos, punto, guion o guion bajo. motivo: texto obligatorio de 1 a 500 caracteres, sin controles ni la marca interna INAC_POR_PAGO; debe poder conservarse en el campo de texto actual del ERP. No se admite GET ni se sustituyen estos campos por parámetros de URL.
Devuelve operacionId, ssid, resultado (inactivada o ya_inactiva), estadoActual, motivoAplicado, fechaUtc y repetida. Si ya estaba inactiva conserva el motivo anterior; el motivo solicitado queda auditado.
El ERP conserva la posibilidad de reactivarla. Repetir la misma clave después de una reactivación devuelve el resultado original y el estado actual, sin volver a suspender. Una nueva suspensión intencional requiere una clave nueva. Una versión sin permiso devuelve 403; cambiar datos con la misma clave devuelve 409.
Descargar JSON de inactivación ↓
05Errores y reintentos
Un timeout no demuestra que la solicitud falló. Repite el mismo POST con la misma clave y contenido. Todas las respuestas de error incluyen error.codigo, error.mensaje, error.campo y error.seguimientoId.
El límite configurado incluye consultas y solicitudes. No hagas sondeos continuos: el ejecutor todavía no está habilitado y el estado permanecerá pendiente.