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.
Crear un contacto con un
externalClientId que ya existe devuelve 409 RESOURCE_CONFLICT.Teléfonos
Cada teléfono tienenumber 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):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.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.
El contacto no tiene
metadata ni operación de borrado (DELETE) en v1. Gestiona su ciclo de vida con PATCH.Endpoints
Pruébalo en el API Reference
Explora cada endpoint con su playground interactivo.