> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Clientes

> Sincroniza la identidad del cliente antes de crear documentos y pagos

<div className="cobrix-category">
  <strong>La misma categoría que ves en el drawer de permisos.</strong>
  <p>Registra o actualiza clientes externos y consulta su estado dentro de la integración. La identidad estable es la combinación de `source` y `externalCustomerId`.</p>
</div>

<div className="cobrix-scope-line">
  <span className="cobrix-scope">customers:read</span>
  <span className="cobrix-scope">customers:write</span>
</div>

## Operaciones

| Permiso del drawer          | Scope             | Método y ruta                                        |
| --------------------------- | ----------------- | ---------------------------------------------------- |
| Listar clientes             | `customers:read`  | `GET /integrations/v1/{companyId}/customers`         |
| Crear y actualizar clientes | `customers:write` | `POST /integrations/v1/{companyId}/customers/upsert` |

<Tabs>
  <Tab title="Crear o actualizar">
    Envía `source`, `externalCustomerId`, `type` y `name`. También puedes conservar `email`, `phone`, `taxId`, `customerCode` y `metadata`.

    El upsert es seguro para sincronizaciones periódicas: la misma identidad actualiza el cliente existente. El `POST` requiere `Idempotency-Key`, firma del request y Bearer.
  </Tab>

  <Tab title="Consultar">
    Filtra por `search`, `externalCustomerId`, `source`, `updatedSince` o `status`. La paginación usa `cursor` y `limit`; conserva el cursor devuelto para obtener la siguiente página.
  </Tab>
</Tabs>

## Identidad que no debe cambiar

<Steps>
  <Step title="Define un source estable">
    Usa el mismo identificador configurado al crear el partner. No lo cambies entre sincronizaciones.
  </Step>

  <Step title="Conserva el ID del sistema externo">
    `externalCustomerId` debe seguir apuntando a la misma persona o empresa durante toda su vida útil.
  </Step>

  <Step title="Referencia esa identidad">
    Los documentos, links y pagos posteriores deben utilizar el mismo `customerExternalId`.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="¿Por qué recibí 403?" icon="shield">
    Verifica que la llave pertenezca al `companyId`, que conserve el `source` autorizado y que tenga `customers:read` o `customers:write` según la operación.
  </Accordion>

  <Accordion title="¿Por qué recibí 409?" icon="triangle-exclamation">
    La identidad o la idempotencia entró en conflicto con una solicitud anterior. Busca el `requestId` en Auditoría y compara el payload enviado.
  </Accordion>
</AccordionGroup>

<Card title="Abrir referencia de clientes" icon="brackets-curly" href="/api-reference/clientes/crear-o-actualizar-cliente" cta="Ver payloads y respuestas" arrow>
  La referencia interactiva muestra cada campo, código HTTP y ejemplo ejecutable.
</Card>