Saltar al contenido
Facturador

Crear cliente o proveedor

POST /api/persons/create/{person_type}

Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).

Registra un cliente (person_type = customers) o proveedor (suppliers) con direcciones adicionales. Es el alta recomendada; Crear cliente o proveedor (alta simple) es la alternativa heredada.

Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).

Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success.

Campo Tipo Obligatorio Descripción / valores permitidos
type string Recomendado Repite el tipo de la URL (customers/suppliers). La validación de número y nombre únicos lo usa: sin él no se detectan duplicados.
identity_document_type_id string Sí Tipo de documento (catálogo SUNAT 06): 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte.
number string Sí Número de documento. Único entre las personas habilitadas del mismo tipo (cliente/proveedor).
name string Sí Nombre o razón social. Único entre las personas habilitadas del mismo tipo.
trade_name string No Nombre comercial.
country_id string Sí País (código ISO de 2 letras, p. ej. PE).
address string No Dirección principal.
telephone string No Teléfono.
email string No Correo. Si se envía debe ser válido y único entre las personas habilitadas.
location_id array No Ubigeo principal [departamento, provincia, distrito], p. ej. ["15", "1501", "150101"] (ver Ubigeos). Si no trae 3 elementos se ignora.
enabled boolean No Habilitado (por defecto true).
addresses array No Direcciones adicionales. Una dirección sin address o sin location_id de 3 elementos se omite.
addresses[].address string Sí Dirección.
addresses[].location_id array Sí Ubigeo [departamento, provincia, distrito].
addresses[].country_id string No País (PE).
addresses[].phone / email string No Teléfono y correo de la dirección.
addresses[].main boolean No Dirección principal.
addresses[].establishment_code string No Código de establecimiento anexo SUNAT (4 dígitos).
addresses[].has_consigned boolean Sí (la clave) true si la dirección pertenece a un consignado. Envía siempre la clave.
addresses[].consigned_id integer No Id del consignado (ver sección Consignaciones, placas, e-commerce y Vendeya) cuando has_consigned es true; su teléfono se actualiza con phone.

Reglas:

  • El tipo se toma de la URL.
  • La respuesta trae la persona creada en data (mismo formato que Ver).

Errores:

  • Validación: 422 con {success: false, message: {campo: [mensajes]}}. Ej.: número o nombre ya registrados, falta country_id.

Parámetros

Parámetro Dónde Obligatorio Ejemplo Descripción
person_type ruta sí customers

Cuerpo

Content-Type: application/json

{
  "type": "customers",
  "identity_document_type_id": "6",
  "number": "20601234567",
  "name": "COMERCIAL NORTE E.I.R.L.",
  "trade_name": "COMERCIAL NORTE",
  "country_id": "PE",
  "address": "AV. PRINCIPAL 123, LIMA",
  "telephone": "987654321",
  "email": "compras@comercialnorte.pe",
  "location_id": [
    "15",
    "1501",
    "150101"
  ],
  "enabled": true,
  "addresses": [
    {
      "id": null,
      "address": "CALLE MERCADERES 456, AREQUIPA",
      "location_id": [
        "04",
        "0401",
        "040101"
      ],
      "country_id": "PE",
      "phone": "054223344",
      "email": "almacen@comercialnorte.pe",
      "main": false,
      "establishment_code": "0001",
      "has_consigned": false,
      "consigned_id": null
    }
  ]
}

Respuestas

200 — Creado

{
  "success": true,
  "message": "Cliente creado exitosamente",
  "data": {
    "id": 25,
    "description": "20601234567 - COMERCIAL NORTE E.I.R.L.",
    "name": "COMERCIAL NORTE E.I.R.L.",
    "number": "20601234567",
    "addresses": [
      {
        "id": 8,
        "trade_name": null,
        "country_id": "PE",
        "location_id": [
          "04",
          "0401",
          "040101"
        ],
        "address": "CALLE MERCADERES 456, AREQUIPA",
        "phone": "054223344",
        "email": "almacen@comercialnorte.pe",
        "main": false,
        "department_id": "04",
        "province_id": "0401",
        "district_id": "040101",
        "establishment_code": "0001",
        "has_consigned": false,
        "consigned_id": null,
        "consigned_name": null
      }
    ],
    "identity_document_type_id": "6",
    "identity_document_type_code": "6",
    "address": "AV. PRINCIPAL 123, LIMA",
    "telephone": "987654321",
    "country_id": "PE",
    "district_id": "150101",
    "email": "compras@comercialnorte.pe",
    "enabled": true,
    "selected": false,
    "identity_document_type_description": "RUC",
    "location_id": [
      "15",
      "1501",
      "150101"
    ]
  }
}

422 — Número repetido

{
  "success": false,
  "message": {
    "number": [
      "El campo número ya ha sido registrado."
    ]
  }
}

Pruébalo

Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.