Cufy API
Clientes guardados

Actualizar un cliente para documentos futuros

PATCH/v1/customers/{id}

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).

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

Header Parameters

Idempotency-Key*string

Obligatoria en mutaciones. Alcance: empresa/ambiente/operación/recurso destino. Retención mínima 90 días y mientras haya trabajo pendiente. Mismo contenido recupera resultado; contenido diferente produce 409.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$
Length1 <= length <= 128
If-Match*string

ETag de versión vigente. Replay idempotente se resuelve ANTES de revalidar If-Match; un comando nuevo con versión antigua produce 409 VERSION_CONFLICT.

Match^"[1-9][0-9]*"$
Length1 <= length <= 30

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Datos fiscales de un comprador para reutilizar al emitir, validados con las mismas reglas del comprador de la factura. external_id es la referencia opcional del ERP: única entre los clientes activos de la empresa y ambiente; archivar un cliente la libera. Al actualizar, el cuerpo reemplaza al cliente completo: omitir external_id lo quita. No hay unicidad por identificación ni fusión de compradores.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/v1/customers/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "buyer": {      "party_type": "company",      "identification": {        "type_code": "10",        "number": "string"      },      "name": "string",      "tax_registration": {        "responsibility_codes": [          "string"        ],        "tax_scheme_codes": [          "string"        ]      }    }  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "external_id": "string",  "buyer": {    "party_type": "company",    "identification": {      "check_digit": "s",      "type_code": "31",      "number": "string"    },    "name": "string",    "address": {      "country_code": "CO",      "department_code": "st",      "municipality_code": "strin",      "city_name": "string",      "line": "string",      "postal_code": "string"    },    "email": "user@example.com",    "tax_registration": {      "responsibility_codes": [        "string"      ],      "tax_scheme_codes": [        "string"      ]    }  },  "status": "active",  "version": 1,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "archived_at": "2019-08-24T14:15:22Z"}

Consultar un cliente guardado GET

**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.

Archivar un cliente 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. If-Match y motivo; irreversible. Libera external_id y deja de admitir documentos nuevos; los admitidos y sus reintentos no cambian. El cliente deja de admitir documentos nuevos y libera su external_id; se sigue consultando y los documentos admitidos no cambian. No se deshace. El motivo queda en auditoría.