Guía de integración

1. 1Cree una API key. Un administrador de su organización entra a https://certeza.app/es/platform/configuraciones/api-keys, pulsa «Nueva llave» y le da un nombre que diga dónde se usará, por ejemplo «ERP producción». La llave completa se muestra una sola vez: cópiela directamente a su gestor de secretos.
2. 2Defina cómo identifica cada registro. Cada cliente se identifica por su tipo y número de documento; cada obligación, por su número de factura (reference_number); cada pago, por su número de recibo (reference). Estos datos no deben cambiar nunca: si cambian, Certeza crea un registro nuevo. Además, en el cliente envíe en external_id el mismo código que usa su sistema contable para ese cliente; así cruzar la información entre los dos sistemas es inmediato.
3. 3Verifique la llave con GET /v1/ (vea Autenticación).
4. 4Cargue y verifique sus datos antes de activar el Piloto automático (vea Cómo probar).

Cómo probar

Certeza no tiene un ambiente de pruebas separado: cada llave escribe en su organización real. Mientras su organización no tenga en el Piloto automático de la plataforma una segmentación activa con su política de cobro, Certeza no contacta a ningún cliente.

1. 1Cargue primero sus clientes, obligaciones y pagos.
2. 2Verifique que saldos, documentos, teléfonos y fechas coincidan con su sistema, consultando la API y revisando algunos clientes en la plataforma.
3. 3Active el Piloto automático después. Desde que una segmentación y su política quedan activas, Certeza empieza a gestionar a los clientes con deuda abierta de ese segmento.

Si su organización ya tiene el Piloto automático activo, cada carga se gestiona desde que llega: verifique los datos antes de enviarlos y empiece con un grupo pequeño de clientes.

Cada solicitud lleva la API key en el encabezado Authorization con el esquema Bearer. Compruebe su llave con la raíz de la API:

curl https://api.certeza.app/api/v1/ \
  -H "Authorization: Bearer $CERTEZA_API_KEY"

{
  "message": "Public API v1",
  "tenant_id": "3f6c2a1e-8d4b-4c1a-9e57-2b8f0d6a41c3",
  "key_name": "ERP producción"
}

key_name es el nombre que le dio a la llave; así confirma cuál está usando. tenant_id es el identificador de su organización en Certeza y no necesita enviarlo en ninguna solicitud. Si la llave falta, es inválida, expiró o fue eliminada, la respuesta es 401 con error_code UNAUTHORIZED.

Cliente customer

La persona o empresa que le debe a su organización. Se identifica por tipo y número de documento (identifier_type + identifier_value).

Obligación obligation

Una deuda concreta: una factura, una cuenta de cobro, una mensualidad de un crédito. Pertenece a un solo cliente y tiene su valor, su fecha de vencimiento y su saldo. Se identifica por reference_number, único en su organización.

Pago payment

Dinero que usted recibió de un cliente. Se aplica a una obligación, o queda a cuenta. Se identifica por reference, el número de su recibo, dentro del cliente que pagó.

Crear y actualizar se hace con el mismo endpoint y con estos identificadores: si el registro no existe se crea, y si existe se actualiza. Su sistema no necesita guardar los identificadores de Certeza (id, obligation_id, payment_id), salvo para leer, modificar o eliminar un registro puntual.

Si vendió a crédito en 12 mensualidades, envíe 12 obligaciones, una por vencimiento, cada una con su reference_number y su due_date.

Carga inicial

El orden importa, porque cada paso usa registros del anterior:

1. 1Clientes con POST /v1/customer/batch.
2. 2Obligaciones con POST /v1/obligations/batch: las que tienen saldo pendiente, con su valor original en amount.
3. 3Pagos con POST /v1/payments/batch: los abonos que ya recibió sobre esas obligaciones, con su fecha real.

Envíe lotes de hasta 500 registros, uno a la vez, y revise failed en cada respuesta.

Sincronización periódica

• Envíe los cambios en el mismo orden: clientes, obligaciones, pagos.
• Le sugerimos enviar solo lo nuevo o lo que cambió: reenviar registros sin cambios no crea duplicados, pero hace que Certeza vuelva a evaluar a esos clientes.
• Envíe cada registro completo, tal como está en su sistema.
• Reporte los pagos tan frecuentemente como pueda. Mientras un pago no llegue a Certeza, el cliente que ya pagó puede seguir recibiendo gestión de cobro.

Reportar pagos

• Un recibo que paga una obligación: un pago con obligation_reference_number.
• Un recibo que paga varias obligaciones: un pago por obligación, con una referencia que combine el recibo y la obligación, por ejemplo RC-871/FV-1001 y RC-871/FV-1002.
• Un pago que aún no sabe a qué obligación aplicar: envíelo con customer_identifier y currency; queda a cuenta y no baja ningún saldo. Indique la obligación siempre que la sepa.

{
  "items": [
    { "reference": "RC-871/FV-1001", "amount": "500000.00",
      "received_date": "2026-09-25", "obligation_reference_number": "FV-1001" },
    { "reference": "RC-871/FV-1002", "amount": "300000.00",
      "received_date": "2026-09-25", "obligation_reference_number": "FV-1002" }
  ]
}

Correcciones y anulaciones

Consultar el estado

• Lo que debe un cliente: GET /v1/obligations filtrando por su documento. outstanding_balance es el saldo de cada obligación y summary.by_currency.*.owed_amount el total.
• Pagos de un periodo: GET /v1/payments?received_date_from=…&received_date_to=….

Los endpoints /batch reciben {"items": [...]} con hasta 500 registros. Si la solicitud se entendió, responden 200 aunque algunos registros hayan fallado: revise failed.

{
  "results": [
    { "index": 0, "key": "FV-1001", "outcome": "created",
      "id": "0b8e7c52-4f3a-4d0e-9a61-6c2d95e1f7a4", "error": null },
    { "index": 1, "key": "FV-1002", "outcome": "failed", "id": null,
      "error": {
        "error_code": "CUSTOMER_NOT_FOUND",
        "http_status": 422,
        "message": "Customer with cedula='1020304050' not found",
        "details": { "identifier_type": "cedula", "identifier_value": "1020304050" }
      } }
  ],
  "created": 1,
  "updated": 0,
  "failed": 1
}

• outcome es created, updated o failed. key es el identificador con el que se buscó el registro y index su posición en la lista (desde 0).
• Un registro rechazado no se escribe y no detiene a los demás. Corríjalo y reenvíe solo ese.
• Si el JSON no cumple el esquema (falta un campo obligatorio, tipo incorrecto), se rechaza el lote completo con 422 y details.validation_errors indica el registro y el campo.
• Ante un 500 o un corte de red, reenvíe el lote completo: no se duplica nada.

Los errores responden con error_code, http_status, message, details y trace_id. Decida según error_code; message es solo informativo. Una ruta que no existe responde 404 con {"detail": "Not Found"}.

Rutas relativas a https://api.certeza.app/api; por ejemplo, /v1/customer es https://api.certeza.app/api/v1/customer. El detalle de cada campo está en Swagger (para probar endpoints) y en ReDoc (para leer la referencia completa).

Clientes

curl -X POST https://api.certeza.app/api/v1/customer \
  -H "Authorization: Bearer $CERTEZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier_type": "cedula",
    "identifier_value": "1020304050",
    "customer_name": "Ana María",
    "last_name": "Pérez Gómez",
    "external_id": "CLI-000123",
    "emails": ["ana.perez@example.com"],
    "mobiles": ["+5730011XXXXX"]
  }'

Obligaciones

curl -X POST https://api.certeza.app/api/v1/obligations/batch \
  -H "Authorization: Bearer $CERTEZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "customer_identifier": { "type": "cedula", "value": "1020304050" },
        "reference_number": "FV-1001",
        "amount": "1000000.00",
        "currency": "COP",
        "issue_date": "2026-09-01",
        "due_date": "2026-09-30",
        "description": "Servicio de internet hogar, septiembre de 2026"
      }
    ]
  }'

Pagos

curl -X POST https://api.certeza.app/api/v1/payments/batch \
  -H "Authorization: Bearer $CERTEZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "reference": "RC-871",
        "amount": "500000.00",
        "received_date": "2026-09-25",
        "obligation_reference_number": "FV-1001"
      }
    ]
  }'

Para dudas de integración o para reportar un error, escriba a su contacto en Certeza. Incluya el endpoint, la hora aproximada, su X-Request-Id y el trace_id de la respuesta. No incluya su API key.