Crear un comercio
Valida el comercio completo y lo acepta para su registro. La respuesta llega antes de que el comercio exista: trae un processId con el que consultar el resultado.
Las tres colecciones del cuerpo —integrations, paymentMethods y sites— tienen reglas propias de identidad y actualización que se explican en Integraciones, Medios de pago y Sitios.
Cabecera
- Name
Authorization- Type
- Authorization
- is Required
- REQUERIDO
- Description
Token de acceso con el permiso
onboarding:create.Ejemplo:Bearer 1|tu-token-de-acceso
- Name
Idempotency-Key- Type
- Idempotency-Key
- is Required
- REQUERIDO
- Description
Identificador único de la operación. Entre 16 y 64 caracteres, y solo puede contener letras, dígitos y los signos
_,.,:y-. Reenviar la misma clave con el mismo contenido devuelve el proceso original en lugar de crear uno nuevo.Ejemplo:8f1c2d3e4a5b6c7d8e9f0a1b
- Name
Content-Type- Type
- Content-Type
- is Required
- REQUERIDO
- Description
- Ejemplo:
application/json
- Name
Accept- Type
- Accept
- is optional
- Description
Recomendado, para que los errores lleguen en formato JSON.
Ejemplo:application/json
Solicitud
Estado del comercio. Los campos viajan en la raíz del cuerpo, junto a las colecciones.
Una clave desconocida en la raíz se ignora en silencio; dentro de un elemento de cualquier
colección, en cambio, responde 422 nombrándola.
- Name
name- Type
- string
- is Required
- REQUERIDO
- Description
Razón social del comercio.
Ejemplo:Comercializadora Acme S.A.S.Longitud máxima:80
- Name
brand- Type
- string
- is Required
- REQUERIDO
- Description
Nombre comercial, el que ve el comprador.
Ejemplo:AcmeLongitud máxima:60
- Name
active- Type
- boolean
- is optional
- Description
Si el comercio queda habilitado.
Valor por defecto:trueEjemplo:true
- Name
url- Type
- string|null
- is optional
- Description
Sitio web del comercio.
Ejemplo:https://acme.example.comFormato:uriLongitud máxima:255
- Name
incrementType- Type
- string
- is optional
- Description
Referencia usada para incrementos.
Valores permitidos:SMLMVIPCEjemplo:SMLMV
- Name
mcc- Type
- string
- is optional
- Description
Código de categoría de comercio. Debe existir en el catálogo.
Ejemplo:5411
- Name
size- Type
- string
- is optional
- Description
Tamaño del comercio, del catálogo de tamaños.
Ejemplo:M
- Name
timezone- Type
- string
- is optional
- Description
Zona horaria en formato IANA, del catálogo de zonas.
Ejemplo:America/Bogota
- Name
languages- Type
- array
- is Required
- REQUERIDO
- Description
Idiomas con los que opera el comercio. Es un conjunto: repetir un valor responde
422, y la comparación ignora mayúsculas.Ejemplo:esen
- Name
currencies- Type
- array
- is Required
- REQUERIDO
- Description
Monedas que el comercio maneja, como códigos ISO del catálogo. Es un conjunto, igual que
languages.Ejemplo:COPUSD
- Name
document- Type
- Document
- is Required
- REQUERIDO
- Description
Documento de identificación fiscal del comercio.
- Name
address- Type
- Address
- is Required
- REQUERIDO
- Description
Dirección fiscal del comercio.
- Name
legalRepresentative- Type
- LegalRepresentative
- is Required
- REQUERIDO
- Description
- Name
billing- Type
- Billing
- is optional
- Description
Datos de facturación del comercio.
- Name
travelAgency- Type
- TravelAgency
- is optional
- Description
Aplicable solo a comercios del sector turismo.
- Name
control- Type
- Control
- is Required
- REQUERIDO
- Description
Estructura comercial bajo la que queda registrado el comercio.
- Name
integrations- Type
- array[Integration]
- is optional
- Description
Integraciones del comercio con proveedores externos. Es un upsert por
type: una integración que el cuerpo no nombra sobrevive intacta, y no hay forma de eliminarla.
- Name
paymentMethods- Type
- array[PaymentMethod]
- is optional
- Description
Medios de pago que el comercio acepta. Un elemento o modifica uno existente por su
id, o registra uno nuevo concode; nunca las dos cosas.
- Name
sites- Type
- array[Site]
- is optional
- Description
Sitios de venta del comercio, con sus propias colecciones.
- Name
notification- Type
- Notification
- is optional
- Description
URL donde recibir el resultado del proceso. Si se omite, no se envía notificación y el resultado se consulta con
GET /api/processes/{processId}.
Solicitud
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 }
}'
Respuesta
La clave de idempotencia ya se había usado con este mismo contenido. Devuelve el proceso
original, con el mismo processId.
- Name
status- Type
- Status
- is Required
- REQUERIDO
- Description
Estado de la petición o del proceso. Presente en todas las respuestas.
El código HTTP dice si la llamada funcionó;
status.statusdice qué pasó con el proceso.
- Name
processId- Type
- string
- is Required
- REQUERIDO
- Description
Identificador del proceso, en minúsculas. Con él se consulta el resultado.
Ejemplo:01kz0609xy2hd666mnx6b0jxpc
- Name
action- Type
- string
- is Required
- REQUERIDO
- Description
Operación pedida.
Valores permitidos:merchant.createmerchant.updateEjemplo:merchant.create
- Name
result- Type
- object|null
- is optional
- Description
Siempre
nullen la aceptación. El resultado llega al consultar el proceso.
- Name
notification- Type
- object|null
- is optional
- Description
Estado de la entrega del webhook, o
nullsi no se registró una URL.
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",
"result": null,
"notification": null
}
Actualizar un comercio
Escribe solo los campos que el cuerpo nombra. El resto del comercio conserva su valor, y ningún campo es obligatorio — pero el cuerpo debe nombrar al menos uno.
Parámetros
- Name
merchantId- Type
- merchantId
- is Required
- REQUERIDO
- Description
Identificador del comercio, tal como lo publica
result.merchantId. Debe ser numérico: uno que no lo sea responde404sin llegar al endpoint.Ejemplo:18
Cabecera
- Name
Authorization- Type
- Authorization
- is Required
- REQUERIDO
- Description
Token de acceso con el permiso
onboarding:update.Ejemplo:Bearer 1|tu-token-de-acceso
- Name
Idempotency-Key- Type
- Idempotency-Key
- is Required
- REQUERIDO
- Description
Identificador único de la operación. El comercio de la URL forma parte de la comparación: la misma clave apuntada a otro comercio responde
409.Ejemplo:4b7e1a9c2d3f5e6a8b0c1d2e
- Name
Content-Type- Type
- Content-Type
- is Required
- REQUERIDO
- Description
- Ejemplo:
application/json
Solicitud
Estado del comercio. Los campos viajan en la raíz del cuerpo, junto a las colecciones.
Una clave desconocida en la raíz se ignora en silencio; dentro de un elemento de cualquier
colección, en cambio, responde 422 nombrándola.
- Name
name- Type
- string
- is Required
- REQUERIDO
- Description
Razón social del comercio.
Ejemplo:Comercializadora Acme S.A.S.Longitud máxima:80
- Name
brand- Type
- string
- is Required
- REQUERIDO
- Description
Nombre comercial, el que ve el comprador.
Ejemplo:AcmeLongitud máxima:60
- Name
active- Type
- boolean
- is optional
- Description
Si el comercio queda habilitado.
Valor por defecto:trueEjemplo:true
- Name
url- Type
- string|null
- is optional
- Description
Sitio web del comercio.
Ejemplo:https://acme.example.comFormato:uriLongitud máxima:255
- Name
incrementType- Type
- string
- is optional
- Description
Referencia usada para incrementos.
Valores permitidos:SMLMVIPCEjemplo:SMLMV
- Name
mcc- Type
- string
- is optional
- Description
Código de categoría de comercio. Debe existir en el catálogo.
Ejemplo:5411
- Name
size- Type
- string
- is optional
- Description
Tamaño del comercio, del catálogo de tamaños.
Ejemplo:M
- Name
timezone- Type
- string
- is optional
- Description
Zona horaria en formato IANA, del catálogo de zonas.
Ejemplo:America/Bogota
- Name
languages- Type
- array
- is Required
- REQUERIDO
- Description
Idiomas con los que opera el comercio. Es un conjunto: repetir un valor responde
422, y la comparación ignora mayúsculas.Ejemplo:esen
- Name
currencies- Type
- array
- is Required
- REQUERIDO
- Description
Monedas que el comercio maneja, como códigos ISO del catálogo. Es un conjunto, igual que
languages.Ejemplo:COPUSD
- Name
document- Type
- Document
- is Required
- REQUERIDO
- Description
Documento de identificación fiscal del comercio.
- Name
address- Type
- Address
- is Required
- REQUERIDO
- Description
Dirección fiscal del comercio.
- Name
legalRepresentative- Type
- LegalRepresentative
- is Required
- REQUERIDO
- Description
- Name
billing- Type
- Billing
- is optional
- Description
Datos de facturación del comercio.
- Name
travelAgency- Type
- TravelAgency
- is optional
- Description
Aplicable solo a comercios del sector turismo.
- Name
control- Type
- Control
- is Required
- REQUERIDO
- Description
Estructura comercial bajo la que queda registrado el comercio.
- Name
integrations- Type
- array[Integration]
- is optional
- Description
Integraciones del comercio con proveedores externos. Es un upsert por
type: una integración que el cuerpo no nombra sobrevive intacta, y no hay forma de eliminarla.
- Name
paymentMethods- Type
- array[PaymentMethod]
- is optional
- Description
Medios de pago que el comercio acepta. Un elemento o modifica uno existente por su
id, o registra uno nuevo concode; nunca las dos cosas.
- Name
sites- Type
- array[Site]
- is optional
- Description
Sitios de venta del comercio, con sus propias colecciones.
- Name
notification- Type
- Notification
- is optional
- Description
URL donde recibir el resultado del proceso. Si se omite, no se envía notificación y el resultado se consulta con
GET /api/processes/{processId}.
Solicitud
curl --request PUT \
--url '{URL_BASE}/api/merchants/18' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TU_TOKEN}' \
--header 'Idempotency-Key: 4b7e1a9c2d3f5e6a8b0c1d2e' \
--data '{ "name": "Comercializadora Acme S.A.S." }'
Respuesta
Replay de una clave de idempotencia ya usada con el mismo contenido.
- Name
status- Type
- Status
- is Required
- REQUERIDO
- Description
Estado de la petición o del proceso. Presente en todas las respuestas.
El código HTTP dice si la llamada funcionó;
status.statusdice qué pasó con el proceso.
- Name
processId- Type
- string
- is Required
- REQUERIDO
- Description
Identificador del proceso, en minúsculas. Con él se consulta el resultado.
Ejemplo:01kz0609xy2hd666mnx6b0jxpc
- Name
action- Type
- string
- is Required
- REQUERIDO
- Description
Operación pedida.
Valores permitidos:merchant.createmerchant.updateEjemplo:merchant.create
- Name
result- Type
- object|null
- is optional
- Description
Siempre
nullen la aceptación. El resultado llega al consultar el proceso.
- Name
notification- Type
- object|null
- is optional
- Description
Estado de la entrega del webhook, o
nullsi no se registró una URL.
Respuesta
{
"status": {
"status": "OK",
"reason": null,
"message": "The request was accepted and will be processed shortly.",
"date": "2026-08-17T10:20:41-05:00"
},
"processId": "01kz0a13bc4de777pqy8c1kxqd",
"action": "merchant.update",
"result": null,
"notification": null
}