Contactos

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.

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.

curl --request POST \
  --url 'https://tapipay-facade.homo.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 }
    ]
  }'

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

Crear un contacto con un externalClientId que ya existe devuelve 409 RESOURCE_CONFLICT. Los campos no declarados en el body se ignoran.

Teléfonos

Cada teléfono tiene number y type obligatorios, y primary y description opcionales. Si no envías description, toma el valor de type (por ejemplo, "MOBILE"). 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):

Por referencia

Envías externalClientId de un contacto existente. Si no existe, devuelve 422 BUSINESS_RULE_VIOLATION.

En línea

Envías contactData con los datos completos. Si el externalClientId no existe, se crea; si ya existe, se actualiza.

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

{
  "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ó).

Buscar contactos

GET /contacts acepta estos filtros, combinables entre sí:

Filtro	Comportamiento
`name`	Búsqueda parcial por nombre.
`email`	Email exacto.
`phone`	Número de teléfono.
`contactCode`	ID público del contacto, con prefijo `con_` o sin él. Match exacto.
`identifier`	Busca por cualquier identificador del contacto: su `externalClientId` o uno secundario (por ejemplo, una referencia de efectivo). Match exacto.
`externalClientId`	Es el mismo filtro que `identifier`. Si envías los dos con valores distintos, la API responde `400 INVALID_REQUEST`.

La paginación usa page (default 1) y limit (default 50, máximo 500). Ver Convenciones de la API.

Actualizar

PATCH /contacts/{id} actualiza name, email o phones. Reglas:

Envía al menos uno de name, email o phones: un body vacío devuelve 400 INVALID_REQUEST.
El externalClientId no es modificable: enviarlo, o cualquier otro campo no listado, devuelve 400.
El email no se puede borrar: "email": null devuelve 400.
phones reemplaza la lista completa. Una lista vacía ("phones": []) devuelve 400; si quieres conservar los teléfonos actuales, omite el campo.
El companyCode del body se toma como contexto de la company, no como un campo a modificar.

curl --request PATCH \
  --url 'https://tapipay-facade.homo.tapila.cloud/contacts/con_9aL3kP2m' \
  --header 'x-api-key: TU_API_KEY' \
  --header 'x-authorization-token: TU_TOKEN_TAPI' \
  --header 'Content-Type: application/json' \
  --data '{
    "phones": [
      { "number": "+5215587654321", "type": "WORK", "primary": true }
    ]
  }'

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

Errores

Además de los errores de validación (400) y de autenticación (ver Autenticación), los endpoints de contactos pueden responder:

Situación	Respuesta
`externalClientId` duplicado al crear	`409 RESOURCE_CONFLICT`
Violación de una regla de negocio al crear	`422 BUSINESS_RULE_VIOLATION`
`companyCode` que no pertenece a tu cliente	`422 RESOLUTION_ERROR`
El contacto se creó pero no se pudo leer de vuelta	`422 RESOLUTION_ERROR` (el contacto existe: consúltalo con `GET /contacts?externalClientId=`)
Falla del servicio de contactos al listar	`500 INTERNAL_ERROR`

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`, `contactCode`, `identifier`, `externalClientId`).
`PATCH`	`/contacts/{id}`	Actualizar `name`, `email` o `phones`.

Pruébalo en el API Reference

Explora cada endpoint con su playground interactivo.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Llave natural: `externalClientId`

Crear un contacto

Teléfonos

Usar el contacto en un cobro

Por referencia

En línea

Buscar contactos

Actualizar

Errores

Endpoints

Pruébalo en el API Reference

​Llave natural: externalClientId

​Crear un contacto

​Teléfonos

​Usar el contacto en un cobro

Por referencia

En línea

​Buscar contactos

​Actualizar

​Errores

​Endpoints

Pruébalo en el API Reference

Llave natural: `externalClientId`

Crear un contacto

Teléfonos

Usar el contacto en un cobro

Buscar contactos

Actualizar

Errores

Endpoints