Cufy API
Clientes guardados

Consultar un cliente guardado

GET/v1/customers/{id}

Estado: implementada. Ambientes: simulation, qualification. Permisos: documents:read.

Alcance: Clientes de la empresa y ambiente de la credencial, con RLS; uno ajeno responde 404 igual que uno inexistente. El comprador se valida con las reglas de la emisión (FISCAL_VALIDATION_FAILED). Sin unicidad por identificación. También archivados, para consultar referencias históricas.

También archivado, para consultar referencias históricas. Uno de otra empresa o ambiente responde 404.

Authorization

ClientApiKey
X-API-Key<token>

Secreto ligado a empresa, actor, permisos y ambiente. No admite cambiar empresa por body/header.

In: header

Path Parameters

id*string

Identificador opaco. No autoriza acceso por sí mismo.

Formatuuid
Length1 <= length <= 36

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "00000000-0000-4000-8000-000000000080",  "external_id": "ERP-CLIENTE-0001",  "buyer": {    "party_type": "person",    "identification": {      "type_code": "13",      "number": "1000000000"    },    "name": "Comprador de ejemplo",    "email": "comprador@example.com",    "tax_registration": {      "responsibility_codes": [        "R-99-PN"      ],      "tax_scheme_codes": [        "01"      ]    }  },  "status": "active",  "version": 1,  "created_at": "2026-09-10T15:00:00Z",  "updated_at": "2026-09-10T15:00:00Z"}

Guardar un cliente para reutilizarlo al emitir POST

**Estado:** implementada. **Ambientes:** simulation, qualification. **Permisos:** `documents:write`. **Alcance:** Clientes de la empresa y ambiente de la credencial, con RLS; uno ajeno responde 404 igual que uno inexistente. El comprador se valida con las reglas de la emisión (FISCAL_VALIDATION_FAILED). Sin unicidad por identificación. Idempotency-Key obligatoria; external_id único entre los activos, también con solicitudes concurrentes (409 CUSTOMER_EXTERNAL_ID_CONFLICT). Valida el comprador con las mismas reglas de la emisión (FISCAL_VALIDATION_FAILED). Repetir la misma Idempotency-Key devuelve el mismo cliente. external_id usado por otro cliente activo: 409 CUSTOMER_EXTERNAL_ID_CONFLICT con resource_id.

Actualizar un cliente para documentos futuros PATCH

**Estado:** implementada. **Ambientes:** simulation, qualification. **Permisos:** `documents:write`. **Alcance:** Clientes de la empresa y ambiente de la credencial, con RLS; uno ajeno responde 404 igual que uno inexistente. El comprador se valida con las reglas de la emisión (FISCAL_VALIDATION_FAILED). Sin unicidad por identificación. If-Match obligatorio; el cuerpo reemplaza al cliente y solo afecta documentos futuros. Un archivado no se edita. El cuerpo reemplaza al cliente completo. No cambia documentos ya admitidos. Un cliente archivado no se edita (409 CUSTOMER_ARCHIVED).