Clientes

Gestión de los clientes (personas o empresas) asociados a tu cuenta.

Tipos de cliente (client_kind)

Valor	Descripción
sa	Sociedad Anónima
srl	Sociedad de Responsabilidad Limitada
pfi	Persona física

Condición fiscal (fiscal)

Códigos aceptados en el body de create/update (persona física):

Código	Descripción
RI	Responsable inscripto
MO	Monotributo
CF	Consumidor final
EX	Exento
NC	No categorizado

---

GET /api/v1/client — Listar clientes

Query params:

Param	Tipo	Default	Notas
page	number	1	mín. 1
limit	number	10	mín. 1, máx. 100
search	string	—	opcional, filtra por texto

Respuesta:

{
  "data": [
    {
      "client_id": "3f9a1c2e-8b4d-4a1e-9c7f-1122aabbccdd",
      "name": "ACME SA",
      "tax_number": "30711111118",
      "fiscal_code": "RI",
      "client_kind": "sa",
      "status": "Active",
      "deprecated": false
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

status puede ser Active, Blocked o Cancelled.

---

GET /api/v1/client/:client_id — Obtener un cliente

Params: client_id (UUID).

Respuesta: un objeto cliente con la forma del item de arriba. 404 si no existe.

---

POST /api/v1/client/create — Crear cliente

Crea un cliente asociado a la cuenta de tu API key.

customer_group_id no va en el body: se toma el grupo activo vinculado a la account de la API key. Si la account no tiene grupo, el customer queda con customer_group_id = null (asignable después).

Body

Campo	Tipo	Requerido	Notas
legal_name	string	sí	1–100 caracteres. Inmutable tras el alta
fiscal	enum	sí	Condición fiscal: RI, MO, CF, EX, NC (ver tabla arriba). Inmutable
tax_number	string	sí	CUIT, 11 dígitos + checksum. Inmutable
client_kind	enum	sí	sa, srl, pfi (ver arriba). Inmutable
address	string	no	1–100. Solo PSP (fulfilled)
postal_code	string	no	Solo PSP (fulfilled)
email	string	no	Solo PSP (fulfilled)
phone	string	no	Solo PSP (fulfilled)
website	string	no	Solo PSP (fulfilled)
locality / city / country / address_extra	string	no	Solo PSP (fulfilled)
address_fiscal / locality_fiscal / city_fiscal / country_fiscal / postal_code_fiscal	string	no	Solo PSP (fulfilled)
transactional_profile_id	string (uuid)	no	Solo PSP (fulfilled)

info

Hacia Core solo se envían legal_name, fiscal, tax_number y client_kind. El resto de campos se guarda en el canal PSP cuando la operación completa (fulfilled). customer_group_id no va en el body: se toma el grupo activo vinculado a la account de la API key.

Ejemplo:

{
  "legal_name": "ACME SA",
  "fiscal": "RI",
  "tax_number": "30711111118",
  "client_kind": "sa",
  "address": "Av. Corrientes 1234",
  "postal_code": "1043",
  "email": "contacto@acme.example",
  "phone": "+541112345678"
}

Headers habituales (x-idempotency, firma, etc.): ver Autenticación.

Respuesta

{
  "operation_core": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
  "operation_status_id": "completed",
  "error": null,
  "response": {
    "result": {
      "data": {
        "client_id": "3f9a1c2e-8b4d-4a1e-9c7f-1122aabbccdd"
      }
    }
  }
}

Campo	Descripción
operation_core	Id de seguimiento en Core cuando está disponible; null si aún no
operation_status_id	Estado (p. ej. completed, pending, failed)
error	Mensaje legible si falló; null si no
response	Detalle del resultado (p. ej. client_id al completar); null si aún no hay

HTTP	Cuándo
200	Completado OK
202	Sigue en curso — si hay operation_core, consultar GET /operation/:operation_id
4xx (p. ej. 422)	Falló; el body puede incluir data con operation_core

tip

El seguimiento de la operación es el id de Core (operation_core). Usá GET /operation/:operation_id cuando ese campo no sea null.

---

PUT /api/v1/client/:client_id — Actualizar datos generales

Update local en PSP (sin operación ni llamada a Core). Solo datos generales.

Path params

Param	Tipo	Requerido	Notas
client_id	string (uuid)	sí	Id del cliente (Core / customer PSP)

Body (todos opcionales)

Campo	Tipo	Notas
phone / email / website	string	Contacto
address / locality / city / country / postal_code / address_extra	string	Domicilio
address_fiscal / locality_fiscal / city_fiscal / country_fiscal / postal_code_fiscal	string	Domicilio fiscal
transactional_profile_id	string (uuid) | null	Perfil transaccional

aviso

No se pueden modificar: nombre legal, CUIT, condición fiscal, tipo de cliente, customer group ni cuenta asociada. Esos campos quedan fijos al crear.

Ejemplo:

{
  "phone": "+541112345678",
  "email": "nuevo@acme.example",
  "website": "https://acme.example",
  "address": "Av. Corrientes 2000"
}

Respuesta: el objeto customer actualizado (200).

---

DELETE /api/v1/client/:client_id — Eliminar cliente

Baja lógica del cliente: queda marcado como deprecado (junto con sus CVU asociados).

Path params

Param	Tipo	Requerido	Notas
client_id	string (uuid)	sí	Cliente a dar de baja

Sin body.

Headers habituales (x-idempotency, firma, etc.): ver Autenticación.

Respuesta

Envelope { operation_core, operation_status_id, error, response } (200 / 202 / 4xx), igual que create. Si sigue en curso y hay operation_core: GET /operation/:operation_id.

Devuelve un error si se reusa la clave de idempotencia (ver Errores).