Datos del comercio

Estos son los campos que describen al comercio como entidad. Viajan en la raíz del cuerpo, junto a las colecciones, y son los mismos en la creación y en la actualización.

Identidad

  • Name
    name
    Type
    string
    is Required
    REQUERIDO
    Description

    Razón social del comercio.

  • Name
    brand
    Type
    string
    is Required
    REQUERIDO
    Description

    Nombre comercial, el que ve el comprador.

  • Name
    active
    Type
    boolean
    is optional
    Description

    Si el comercio queda habilitado. Por defecto, true.

  • Name
    url
    Type
    string
    is optional
    Description

    Sitio web del comercio.

  • Name
    mcc
    Type
    string
    is optional
    Description

    Código de categoría de comercio. Debe existir en el catálogo.

  • Name
    size
    Type
    string
    is optional
    Description

    Tamaño del comercio, según el catálogo de tamaños.

  • Name
    timezone
    Type
    string
    is optional
    Description

    Zona horaria en formato IANA, por ejemplo America/Bogota.

  • Name
    incrementType
    Type
    string
    is optional
    Description

    Referencia usada para incrementos: SMLMV o IPC.

Identidad

{
  "name": "Comercializadora Acme S.A.S.",
  "brand": "Acme",
  "active": true,
  "url": "https://acme.example.com",
  "mcc": "5411",
  "size": "M",
  "timezone": "America/Bogota",
  "incrementType": "SMLMV"
}

Los campos marcados como requeridos lo son al crear un comercio. En una actualización ninguno lo es: se escribe lo que el cuerpo nombra y el resto conserva su valor. Ver Actualizar un comercio.

Idiomas y monedas

  • Name
    languages
    Type
    array
    is Required
    REQUERIDO
    Description

    Idiomas con los que opera el comercio, como códigos del catálogo.

  • Name
    currencies
    Type
    array
    is Required
    REQUERIDO
    Description

    Monedas que el comercio maneja, como códigos ISO del catálogo.

Ambas son obligatorias y deben traer al menos un elemento.

Idiomas y monedas

{
  "languages": ["es", "en"],
  "currencies": ["COP", "USD"]
}

Las dos son conjuntos: repetir un valor responde 422. Y la comparación ignora mayúsculas, así que ["COP", "cop"] cuenta como repetido.

Documento

  • Name
    document
    Type
    object
    is Required
    REQUERIDO
    Description

    Documento de identificación fiscal del comercio.

  • Name
    document.type
    Type
    string
    is optional
    Description

    Tipo de documento. Obligatorio si envías document.number.

  • Name
    document.number
    Type
    string
    is optional
    Description

    Número del documento. Se valida según el tipo declarado, de modo que un número con formato incorrecto para ese tipo responde 422.

Los tipos admitidos dependen del país. Envía siempre el par completo.

Documento

{
  "document": {
    "type": "NIT",
    "number": "9001234567"
  }
}

Dirección

  • Name
    address
    Type
    object
    is Required
    REQUERIDO
    Description

    Dirección fiscal del comercio.

  • Name
    address.street
    Type
    string
    is optional
    Description

    Calle, número y demás detalles de la dirección.

  • Name
    address.city
    Type
    string
    is Required
    REQUERIDO
    Description

    Ciudad. Es texto libre.

  • Name
    address.country
    Type
    string
    is Required
    REQUERIDO
    Description

    Código del país, del catálogo de países.

  • Name
    address.state
    Type
    integer
    is Required
    REQUERIDO
    Description

    Identificador de la provincia o departamento. Debe pertenecer al país que envías en address.country.

  • Name
    address.phone
    Type
    string
    is optional
    Description

    Teléfono de contacto.

  • Name
    address.postalCode
    Type
    string
    is optional
    Description

    Código postal. Se valida según el formato del país.

Dirección

{
  "address": {
    "street": "Carrera 43A # 1-50, Torre 2",
    "city": "Bogota",
    "country": "CO",
    "state": 11,
    "phone": "6013905000",
    "postalCode": "110111"
  }
}
  • Name
    legalRepresentative.name
    Type
    string
    is Required
    REQUERIDO
    Description

    Nombre del representante legal.

  • Name
    legalRepresentative.surname
    Type
    string
    is Required
    REQUERIDO
    Description

    Apellido del representante legal.

  • Name
    legalRepresentative.documentType
    Type
    string
    is optional
    Description

    Tipo de documento. Obligatorio si envías el documento.

  • Name
    legalRepresentative.document
    Type
    string
    is optional
    Description

    Número de documento, validado según el tipo declarado.

Representante legal

{
  "legalRepresentative": {
    "name": "Ada",
    "surname": "Lovelace",
    "documentType": "CC",
    "document": "1020304050"
  }
}

Facturación

Todo el bloque es opcional.

  • Name
    billing.contact
    Type
    string
    is optional
    Description

    Persona o área de contacto para facturación.

  • Name
    billing.mail
    Type
    string
    is optional
    Description

    Correo de facturación.

  • Name
    billing.registrationNumber
    Type
    string
    is optional
    Description

    Número de registro mercantil.

  • Name
    billing.ciiu
    Type
    string
    is optional
    Description

    Código de actividad económica.

  • Name
    billing.taxType
    Type
    integer
    is optional
    Description

    Tipo de contribuyente, del catálogo correspondiente.

  • Name
    billing.taxRegime
    Type
    integer
    is optional
    Description

    Régimen tributario, del catálogo correspondiente.

  • Name
    billing.organizationType
    Type
    integer
    is optional
    Description

    Tipo de sociedad, del catálogo correspondiente.

Facturación

{
  "billing": {
    "contact": "Contabilidad Acme",
    "mail": "[email protected]",
    "registrationNumber": "9001234567-1",
    "ciiu": "4791",
    "taxType": 1,
    "taxRegime": 1,
    "organizationType": 1
  }
}

Agencia de viajes

Bloque opcional, aplicable solo a comercios del sector turismo.

  • Name
    travelAgency.dispersion
    Type
    boolean
    is optional
    Description

    Si el comercio opera con dispersión de fondos.

  • Name
    travelAgency.iata
    Type
    string
    is optional
    Description

    Código IATA de la agencia.

Agencia de viajes

{
  "travelAgency": {
    "dispersion": false,
    "iata": "ABCD12"
  }
}

Control comercial

Define bajo qué estructura comercial queda registrado el comercio.

  • Name
    control.reseller
    Type
    integer
    is Required
    REQUERIDO
    Description

    Intermediario comercial al que pertenece el comercio. Debe estar habilitado en el momento de la creación.

  • Name
    control.seller
    Type
    integer
    is optional
    Description

    Vendedor asociado. Debe estar habilitado.

  • Name
    control.paymentFacilitator
    Type
    integer
    is optional
    Description

    Facilitador de pagos, cuando aplique. Admite null.

En una actualización, control.reseller y control.seller aceptan además el valor que el comercio ya tiene, aunque haya dejado de estar habilitado. Ver Actualizar un comercio.

Control

{
  "control": {
    "reseller": 1,
    "seller": 1,
    "paymentFacilitator": null
  }
}

Campos que se rechazan

El identificador del comercio no viaja en el cuerpo. Estas dos grafías responden 422 en ambos endpoints:

Campo
Por qué
Dónde va
id
El comercio se identifica por la URL
En la ruta del PUT
merchantId
Igual que el anterior
En la ruta del PUT

Se rechazan explícitamente en lugar de ignorarse: un campo que simplemente se descarta es peor que uno que se rechaza, porque quien llama se queda creyendo que direccionó otro recurso.

¿Qué sigue?