Primeros pasos

Esta página recorre una integración completa con el comercio más simple que Onboarding acepta: nueve campos. Cuando la termines tendrás un comercio registrado y sabrás cómo obtener su identificador.

Lo que necesitas

  • Tu token de acceso y la URL base del ambiente donde vas a trabajar. Si aún no los tienes, consulta Autenticación.
  • Que tu token incluya el permiso onboarding:create.
  • Una herramienta para hacer peticiones HTTP desde tu servidor.

En los ejemplos, {URL_BASE} es la URL del ambiente y {TU_TOKEN} es tu token de acceso.

1. Envía el comercio

El cuerpo mínimo contiene solo lo que Onboarding exige: cómo se llama el comercio, con qué idiomas y monedas opera, su documento, su dirección, su representante legal y bajo qué intermediario comercial queda registrado.

El header Idempotency-Key es obligatorio. Genera un identificador único para esta operación y guárdalo antes de enviar la petición: si la llamada falla por un problema de red, reenviarla con esa misma clave evita crear un comercio duplicado. Lo explicamos en detalle en Idempotencia.

Solicitud

POST
/api/merchants
curl --request POST \
  --url '{URL_BASE}/api/merchants' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {TU_TOKEN}' \
  --header 'Idempotency-Key: 8f1c2d3e4a5b6c7d8e9f0a1b' \
  --data '{
    "name": "Comercializadora Acme S.A.S.",
    "brand": "Acme",
    "languages": ["es"],
    "currencies": ["COP"],
    "document": { "type": "NIT", "number": "9001234567" },
    "address": { "city": "Bogota", "country": "CO", "state": 11 },
    "legalRepresentative": { "name": "Ada", "surname": "Lovelace" },
    "control": { "reseller": 1 }
  }'

2. Lee la respuesta

Si el contenido es válido, Onboarding responde 202 y devuelve el identificador del proceso.

Respuesta

{
  "status": {
    "status": "OK",
    "reason": null,
    "message": "The request was accepted and will be processed shortly.",
    "date": "2026-08-17T10:14:03-05:00"
  },
  "processId": "01kz0609xy2hd666mnx6b0jxpc",
  "action": "merchant.create"
}

La respuesta trae además dos headers:

Header
Valor de ejemplo
Para qué sirve
Location
/api/processes/01kz0609xy2hd666mnx6b0jxpc
La URL exacta donde consultar el proceso
Retry-After
5
Cuántos segundos esperar antes de la primera consulta

Un 202 con status.status en OK significa «acepté tu petición», no «el comercio ya existe». En este punto el comercio todavía no está registrado.

3. Consulta el proceso

Con el processId consulta el estado hasta que la respuesta deje de traer el header Retry-After.

Solicitud

GET
/api/processes/{processId}
curl --request GET \
  --url '{URL_BASE}/api/processes/01kz0609xy2hd666mnx6b0jxpc' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {TU_TOKEN}'

Verás una de estas tres respuestas:

Respuesta

{
  "status": {
    "status": "PENDING",
    "reason": null,
    "message": "The request is waiting to be processed.",
    "date": "2026-08-17T10:14:03-05:00"
  },
  "processId": "01kz0609xy2hd666mnx6b0jxpc",
  "action": "merchant.create",
  "result": null,
  "notification": null
}

Las tres respuestas llegan con código HTTP 200, incluida la que informa de un fallo: la consulta funcionó correctamente y te está diciendo qué pasó. Ver Errores.

4. Guarda el identificador del comercio

Cuando el proceso termina bien, result.merchantId contiene el identificador del comercio registrado. Guárdalo: es el que usarás para actualizarlo más adelante.

No confundas los dos identificadores:

Identificador
Qué es
Formato
processId
La operación que pediste
Cadena de texto en minúsculas
result.merchantId
El comercio registrado
Número entero

Lista de comprobación

Antes de dar la integración por terminada, revisa estos ocho puntos. Cada uno corresponde a un error frecuente:

  1. Guardas la clave de idempotencia antes de enviar la petición, no después de recibir la respuesta.
  2. Usas una clave por intención, no por intento: reintentar la misma operación reutiliza la clave.
  3. Tu polling respeta Retry-After en lugar de usar un intervalo fijo.
  4. Dejas de consultar cuando desaparece Retry-After, no cuando ves un valor concreto.
  5. Tratas un proceso FAILED como una respuesta 200, no como un error de red.
  6. Tu manejo de status.reason tiene un caso por defecto, porque pueden aparecer códigos nuevos.
  7. Si usas notificaciones, deduplicas por X-Event-Id y respondes 2xx en cuanto verificas la firma.
  8. Tienes una consulta de respaldo para los casos en que la notificación no llegue.

¿Qué sigue?