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

# Contactos

> El deudor reutilizable: centraliza los datos de quien paga para reutilizarlo en varios cobros.

Un **contacto** (`Contact`) representa al **deudor**: la persona o entidad a quien le cobras. Centraliza sus datos (nombre, email, teléfonos) para que puedas reutilizarlo en cobros futuros sin repetir la información.

**Cuándo crearlo explícitamente:** cuando quieres mantener un padrón de deudores o reutilizar al mismo en varios cobros. Si solo cobras una vez, alcanza con crearlo en línea al crear la [deuda](/es/recursos/deudas).

## Llave natural: `externalClientId`

El `externalClientId` es la llave natural del contacto y es **única por organización**. Es el valor con el que referencias al deudor en deudas y suscripciones. El `contactId` (con prefijo `con_`) es el identificador que asigna TapiPay.

## Crear un contacto

`externalClientId`, `name` y `email` son obligatorios.

```bash theme={null}
curl --request POST \
  --url 'https://tapipay-facade.dev.tapila.cloud/contacts' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalClientId": "CLI-00042",
    "name": "Cliente Ejemplo",
    "email": "cliente@example.com",
    "phones": [
      { "number": "+5215512345678", "type": "MOBILE", "primary": true }
    ]
  }'
```

```json theme={null}
{
  "data": {
    "contactId": "con_9aL3kP2m",
    "externalClientId": "CLI-00042",
    "name": "Cliente Ejemplo",
    "email": "cliente@example.com",
    "phones": [
      { "number": "+5215512345678", "type": "MOBILE", "primary": true, "description": null }
    ],
    "active": true,
    "createdAt": "2026-06-03T18:05:00Z",
    "updatedAt": "2026-06-03T18:05:00Z"
  },
  "requestId": "req_a1b2c3d4"
}
```

<Note>
  Crear un contacto con un `externalClientId` que ya existe devuelve `409 RESOURCE_CONFLICT`.
</Note>

### Teléfonos

Cada teléfono tiene `number` y `type` obligatorios, y `primary` y `description` opcionales. El `type` debe ser uno de:

`MAIN`, `MOBILE`, `WORK`, `RELATIVE`, `OTHER`.

Un `type` fuera de esa lista devuelve `400 INVALID_REQUEST`.

## Usar el contacto en un cobro

En una deuda o suscripción identificas al deudor de **una** de estas dos formas (exactamente una):

<CardGroup cols={2}>
  <Card title="Por referencia" icon="link">
    Envías `externalClientId` de un contacto existente. Si no existe, devuelve `422 BUSINESS_RULE_VIOLATION`.
  </Card>

  <Card title="En línea" icon="user-plus">
    Envías `contactData` con los datos completos. Si el `externalClientId` no existe, se crea; si ya existe, se actualiza.
  </Card>
</CardGroup>

En la respuesta del cobro, el contacto viene embebido con tres campos:

```json theme={null}
{
  "contact": {
    "contactId": "con_9aL3kP2m",
    "externalClientId": "CLI-00042",
    "createdInline": true
  }
}
```

`createdInline` es `true` si el contacto se creó en esa petición, y `false` si ya existía (se reutilizó o se actualizó).

## Actualizar

`PATCH /contacts/{id}` actualiza `name`, `email` o `phones` (al menos uno). El `externalClientId` **no es modificable**. Al actualizar `phones`, la lista enviada reemplaza por completo la anterior.

<Note>
  El contacto no tiene `metadata` ni operación de borrado (`DELETE`) en v1. Gestiona su ciclo de vida con `PATCH`.
</Note>

## Endpoints

| Método  | Ruta             | Descripción                                                                             |
| ------- | ---------------- | --------------------------------------------------------------------------------------- |
| `POST`  | `/contacts`      | Crear un contacto.                                                                      |
| `GET`   | `/contacts/{id}` | Consultar un contacto.                                                                  |
| `GET`   | `/contacts`      | Listar contactos (filtros `name`, `email`, `phone`, `externalClientId`, `contactCode`). |
| `PATCH` | `/contacts/{id}` | Actualizar `name`, `email` o `phones`.                                                  |

<Card title="Pruébalo en el API Reference" icon="play" href="/api-reference">
  Explora cada endpoint con su playground interactivo.
</Card>