Clientes guardados

Un cliente guardado es el comprador de tus facturas (buyer) con un id propio. Lo creas una vez y, al facturar, envías customer_id en lugar del comprador completo.

Enviar el comprador completo en cada factura sigue funcionando igual. Los clientes son una opción, no un requisito. En el sandbox también los creas y editas desde el panel, en Clientes.

Crear un cliente

Envía el mismo objeto buyer que usarías en una factura con POST /v1/customers. external_id es opcional: es el código del cliente en tu ERP.

{
  "external_id": "ERP-CLIENTE-0001",
  "buyer": {
    "party_type": "company",
    "identification": { "type_code": "31", "number": "900123456", "check_digit": "7" },
    "name": "Ferretería Ejemplo S.A.S.",
    "address": {
      "country_code": "CO",
      "department_code": "11",
      "municipality_code": "11001",
      "city_name": "Bogotá",
      "line": "Calle 100 # 10-20"
    },
    "email": "facturas@example.com",
    "tax_registration": { "responsibility_codes": ["O-13"], "tax_scheme_codes": ["01"] }
  }
}

Responde 201 con el cliente, su id y su version:

{
  "id": "5b7c2f0e-8a41-4c7e-9d0b-2f1e6a3c9d10",
  "external_id": "ERP-CLIENTE-0001",
  "buyer": { "party_type": "company", "name": "Ferretería Ejemplo S.A.S.", "…": "…" },
  "status": "active",
  "version": 1,
  "created_at": "2026-09-27T15:00:00.000Z",
  "updated_at": "2026-09-27T15:00:00.000Z"
}

• El comprador pasa las mismas reglas que en una factura. Si algo falla, responde 422 FISCAL_VALIDATION_FAILED con los errores en /buyer/..., igual que POST /v1/invoice-validations.
• Lleva Idempotency-Key: repetir la petición con la misma clave devuelve el mismo cliente.
• external_id no se repite entre tus clientes activos: otro cliente activo con el mismo valor responde 409 CUSTOMER_EXTERNAL_ID_CONFLICT con su resource_id.
• Dos clientes pueden tener el mismo NIT o cédula. Cufy no los fusiona ni los corrige.

Facturar con un cliente

Envía customer_id en el lugar de buyer. El resto de la factura no cambia.

{
  "document_type": "invoice",
  "external_reference": "PEDIDO-2001",
  "profile_id": "co-sale-cop-v1",
  "numbering_range_id": "00000000-0000-4000-8000-000000000010",
  "issued_at": "2026-09-27T10:00:00-05:00",
  "currency": "COP",
  "customer_id": "5b7c2f0e-8a41-4c7e-9d0b-2f1e6a3c9d10",
  "lines": [
    {
      "id": "1",
      "description": "Servicio de ejemplo",
      "product_identification": { "scheme_code": "999", "value": "SERV-001" },
      "quantity": "1",
      "unit_code": "94",
      "unit_price": "10000.00",
      "price_base_quantity": "1",
      "net_amount": "10000.00",
      "adjustments": [],
      "taxes": [{ "code": "01", "rate": "19", "taxable_amount": "10000.00", "amount": "1900.00" }],
      "withholdings": []
    }
  ],
  "adjustments": [],
  "tax_totals": [{ "code": "01", "rate": "19", "taxable_amount": "10000.00", "amount": "1900.00" }],
  "withholding_totals": [],
  "totals": {
    "line_extension_amount": "10000.00",
    "tax_exclusive_amount": "10000.00",
    "tax_inclusive_amount": "11900.00",
    "allowance_total_amount": "0.00",
    "charge_total_amount": "0.00",
    "prepaid_amount": "0.00",
    "payable_rounding_amount": "0.00",
    "payable_amount": "11900.00"
  },
  "payment": { "terms": "cash", "means_code": "10" }
}

Envía o buyer o customer_id:

customer_id se admite en:

• POST /v1/invoices (facturas).
• POST /v1/pos-receipts (documento equivalente POS).
• POST /v1/invoice-validations (revisar sin enviar). Con un cliente archivado responde 200 con valid: false y el error CUSTOMER_ARCHIVED.

No se admite en las notas crédito y débito ni en su revisión, porque una nota repite el comprador exacto de su factura: envía buyer con los datos que llevó la factura. Tampoco en la corrección de un rechazo. En esas rutas customer_id responde 422 CUSTOMER_ID_NOT_SUPPORTED.

GET /v1/documents/{id} incluye customer_id cuando la factura se envió con un cliente guardado.

La factura no cambia si el cliente cambia

Al recibir la factura, Cufy copia los datos del cliente en ella. El XML, el PDF, el envío a la DIAN y las notas usan esa copia.

• Editar o archivar el cliente después no cambia facturas ya recibidas.
• Reintentar una factura ya recibida (misma Idempotency-Key, o mismo external_reference con el mismo cuerpo) devuelve la misma factura, aunque el cliente haya cambiado o esté archivado.

Buscar y listar

GET /v1/customers trae primero los más recientes, solo los activos si no dices otra cosa.

Una lista recorrida por páginas no repite ni salta clientes aunque alguien los edite mientras tanto. Los creados después de la primera página aparecen cuando empiezas de nuevo.

Editar

PATCH /v1/customers/{id} recibe el cliente completo (external_id y buyer) y reemplaza el anterior. Si omites external_id, se quita.

Lleva If-Match con la versión que leíste ("1", "2"…). Si otra persona lo cambió antes, responde 409 VERSION_CONFLICT: vuelve a leerlo y repite el cambio sobre la versión nueva. Sin If-Match responde 428.

Los cambios solo aplican a las facturas que envíes después.

Archivar

POST /v1/customers/{id}/archival con If-Match y un motivo:

{ "reason": "El cliente cerró su cuenta" }

Un cliente archivado:

• Sigue apareciendo en GET /v1/customers/{id} y con status=archived en la lista.
• No admite facturas nuevas ni cambios (409 CUSTOMER_ARCHIVED).
• Libera su external_id: puedes crear otro cliente activo con el mismo código.

Archivar no se puede deshacer.

Permisos

Leer clientes pide documents:read; crearlos, editarlos o archivarlos, documents:write. Son los mismos permisos de las facturas, así que las claves que ya emiten pueden usarlos sin cambios.

Cada cliente pertenece a tu empresa y a tu ambiente. Un cliente de otra empresa, o del otro ambiente de la tuya, no existe para ti: responde 404.