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:
422con{success: false, message: {campo: [mensajes]}}. Ej.: número o nombre ya registrados, faltacountry_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.