Cómo funciona la integración

Payana recibe las facturas de tus proveedores desde la entidad fiscal (DIAN en Colombia, SAT en México), las clasifica, las hace aprobar y arma el comprobante contable completo: cuentas, impuestos, retenciones, centros de costo y el cruce contra órdenes de compra o entradas de almacén.

Colombia y México usan nombres distintos para lo mismo. En Colombia a este proceso se lo llama causación; en México, registro o contabilización de facturas. En esta documentación vas a ver los dos términos: el evento del webhook se llama document.accounted y el motor que arma el comprobante es el de causación, pero el proceso es el mismo en ambos países.

Esta sección es para los ERPs que Payana no integra de forma nativa. Si tu empresa usa SAP, NetSuite, Siigo, Odoo, SIESA o Dynamics, no necesitás implementar nada de esto: Payana ya se conecta directo y la configuración está en Integraciones con ERPs. Si tu ERP no está en esa lista —uno propio, uno local, o cualquiera que no integremos todavía— esta guía es para tu equipo de tecnología. Tenés que implementar dos cosas, y son independientes entre sí:

Sincronización del catálogo. Tu sistema envía a Payana los datos maestros del ERP —proveedores, cuentas contables, impuestos, centros de costo, órdenes de compra— para que el motor de causación pueda usarlos.
Recepción del webhook. Cuando Payana termina de armar el comprobante, tu sistema lo recibe, lo registra en el ERP y responde con el consecutivo.

Arquitectura

La integración son tres procesos separados en el tiempo. Esto es lo primero que conviene entender, porque condiciona todo lo demás: enviarnos parámetros no devuelve una causación. Payana trabaja por su cuenta en el medio, y el comprobante llega mucho después, por webhook. Etapa 1 — Enviás el catálogo. Cada vez que algo cambie en tu ERP. No dispara nada: solo deja los parámetros disponibles para cuando haga falta imputar. Etapa 2 — Payana trabaja sola. Recibe las facturas de la entidad fiscal, las clasifica, las hace aprobar por quien corresponda y finalmente las causa usando los parámetros que enviaste. Esta etapa puede tardar días o semanas, y no hay relación uno a uno con lo que mandaste: un envío de catálogo no produce una causación, y una causación puede usar parámetros que enviaste hace meses. Etapa 3 — Recibís y confirmás. Llega el webhook con el comprobante armado. Tu sistema lo registra en el ERP y responde con el consecutivo bajo el que quedó, o con el error para que Payana se lo muestre al cliente y permita reintentar. Payana no accede a tu ERP en ningún momento, ni siquiera en la etapa 3: siempre es tu sistema el que escribe. La causación puede resolverse de tres formas, según lo que tenga la operación: directa contra cuentas contables, contra orden de compra o entrada de almacén —arrastrando las imputaciones del documento cruzado— o como legalización de un anticipo ya entregado. Las dos primeras producen contratos de salida distintos, porque casi ningún ERP las recibe por el mismo endpoint.

Cerrar el círculo

Después de registrar el comprobante hay un paso que suele olvidarse y que es el que más problemas causa: devolverle a Payana el estado actualizado de lo que la factura consumió —cantidades facturadas de la orden de compra, saldo restante del anticipo—. Eso es otra vez la etapa 1. Si no lo hacés, Payana va a volver a ofrecer para causar algo que ya se facturó.

Autenticación

Todos los endpoints usan la API key de tu empresa en el header api-key:

api-key: your_api_key_here

La key identifica a la empresa. No hace falta enviar un identificador de empresa en el body: Payana lo resuelve a partir de la key. Base URLs

Producción: https://api.prod.payana.cloud/public/api/v1
Develop: https://api.develop.payana.cloud/public/api/v1

Pedí una key de Develop para integrar y probar antes de pasar a producción.

Modelo de identidad

Esta es la parte que más conviene entender antes de escribir código. Todo registro, sin excepción, se identifica por su external_id: el ID que ese registro tiene en tu ERP. Vos nunca manejás identificadores internos de Payana. Cuando una entidad necesita referenciar a otra, lo hace por el external_id de la otra, con un campo que termina en _external_id:

{
  "external_id": "PROD-114",
  "name": "Servicio de mantenimiento",
  "book_account_external_id": "5135",
  "tax_external_id": "IVA-19"
}

Payana mantiene internamente su propia tabla de correspondencias y resuelve esas referencias. Si enviás un *_external_id que todavía no existe, el registro se rechaza con VALIDATION_ERROR — por eso importa el orden de carga.

El external_id tiene que ser estable en el tiempo. Es la llave con la que Payana reconoce que un registro que ya vio volvió a llegar. Si tu ERP reasigna IDs, o si mandás un identificador derivado (un hash del nombre, un consecutivo de la exportación), cada sincronización va a crear duplicados en lugar de actualizar.

Orden de carga

Las entidades tienen dependencias entre sí. En una carga inicial respetá este orden, porque cada grupo referencia a los anteriores:

Orden	Entidades	Depende de
1	Proveedores · Cuentas contables · Impuestos · Centros de costo · Bodegas · Tipos de documento · Métodos de pago · Condiciones de pago · Monedas	—
2	Productos · Anticipos de proveedor	Grupo 1
3	Órdenes de compra · Entradas de almacén	Grupos 1 y 2

Una vez cargado el catálogo inicial, las actualizaciones incrementales pueden ir en cualquier orden, siempre que lo referenciado ya exista.

Formato de los endpoints

Hay un endpoint por entidad, todos con la misma forma. Aceptan hasta 500 registros por request en items:

POST https://api.prod.payana.cloud/public/api/v1/erp/cost-centers
api-key: your_api_key_here
Content-Type: application/json

{
  "items": [
    { "external_id": "CC-001", "code": "ADM", "name": "Administración" },
    { "external_id": "CC-002", "code": "VTA", "name": "Ventas", "parent_external_id": "CC-001" }
  ]
}

En el resto de la documentación los endpoints se escriben en su forma corta —/erp/cost-centers— siempre relativa a la base pública https://api.prod.payana.cloud/public/api/v1. Respuesta Cuando todos los registros entran, la respuesta es 200:

{
  "total": 2,
  "synced": 2,
  "skipped": 0,
  "errors": []
}

Cuando alguno falla, el resto se procesa igual y la respuesta es 207 Multi-Status con el detalle por registro, siguiendo el formato de problem details de la RFC 9457:

{
  "type": "https://docs.payana.la/errors/batch-sync-error",
  "title": "Error en sincronización de centros de costo",
  "status": 207,
  "detail": "Algunos registros no pudieron sincronizarse.",
  "instance": "/erp/cost-centers",
  "total": 5,
  "synced": 3,
  "skipped": 2,
  "errors": [
    {
      "index": 1,
      "external_id": "CC-002",
      "action": "skipped",
      "code": "VALIDATION_ERROR",
      "field": "code",
      "detail": "El campo 'code' es obligatorio."
    },
    {
      "index": 3,
      "external_id": "CC-004",
      "action": "skipped",
      "code": "DUPLICATE_EXTERNAL_ID",
      "field": "external_id",
      "detail": "Ya existe un centro de costo con este external_id."
    }
  ]
}

Campo	Descripción
`total`	Registros recibidos en el request
`synced`	Registros creados o actualizados
`skipped`	Registros que no entraron
`errors[].index`	Posición del registro en el array `items` que enviaste, empezando en `0`
`errors[].external_id`	El `external_id` del registro, para ubicarlo sin depender de la posición
`errors[].action`	Qué pasó con ese registro. Hoy siempre `skipped`
`errors[].code`	Código estable, apto para ramificar por código
`errors[].field`	El campo que causó el rechazo, cuando el error es atribuible a uno
`errors[].detail`	Mensaje legible. No lo parsees: puede cambiar

Un 207 no es un fallo del request: parte se guardó. Revisá siempre errors aunque el status sea 2xx, y reintentá solo los registros que fallaron. El listado completo de entidades y el contrato de campos de cada una está en Catálogo de entidades.

Idempotencia

Los endpoints son upsert: si el external_id ya existe, el registro se actualiza; si no, se crea. Podés reenviar el mismo lote sin generar duplicados, lo que hace que reintentar tras un error de red sea seguro.

Bajas y registros inactivos

Payana nunca da de baja nada por su cuenta. Un registro que dejás de enviar sigue activo: que no aparezca en un request no significa que se haya eliminado en tu ERP, solo que no vino en ese lote. Las bajas son siempre explícitas. Para desactivar un registro, mandalo con is_active en false:

{ "items": [{ "external_id": "CC-002", "is_active": false }] }

Podés reactivarlo después con is_active: true, o simplemente volviendo a enviarlo completo.

Esto pone la detección de bajas de tu lado. Si tu ERP elimina registros en vez de marcarlos como inactivos, tu integración tiene que darse cuenta de que desaparecieron y avisarlo: comparando contra la última sincronización, o leyendo el log de auditoría del ERP si lo tiene. Un centro de costo que borraste y nunca reportaste va a seguir apareciendo para causar.

Los registros desactivados no desaparecen: dejan de ofrecerse para causar documentos nuevos, pero se conservan para no romper los comprobantes históricos que los usan.

Frecuencia

No hay una frecuencia impuesta; depende de cuánto se mueva cada entidad.

Catálogo estable (cuentas contables, impuestos, centros de costo, tipos de documento): una sincronización diaria alcanza.
Catálogo que se mueve (proveedores, productos): diaria o al detectar el cambio en tu ERP.
Documentos operativos (órdenes de compra, entradas de almacén): tan seguido como las necesites para causar. Si tu operación causa contra OC del día, sincronizalas cada pocas horas o al aprobarse la OC.

Salida: el webhook del comprobante

Cuando un documento termina de causarse, Payana hace un POST al endpoint que registres, firmado con HMAC SHA256. El payload trae el comprobante contable armado: líneas con su cuenta, impuestos discriminados, retenciones calculadas, distribución por centro de costo y el cruce contra la OC o la entrada de almacén cuando corresponde.

Webhook de causación

Contrato de salida y cómo mapearlo de vuelta a tu ERP.

Próximos pasos

Catálogo de entidades — el contrato de cada entidad de entrada.
Webhook del comprobante — el contrato de salida.
Introducción a la API — autenticación, errores y límites de uso.

API documentation

Documentos

Flujos de documentos

Payments

Beneficiaries

Banks

DIAN Events

Fiscal Sync

Registro de facturas en ERPs externos

Guías de Integración

Cómo funciona la integración

Arquitectura

Cerrar el círculo

Autenticación

Modelo de identidad

Orden de carga

Formato de los endpoints

Idempotencia

Bajas y registros inactivos

Frecuencia

Salida: el webhook del comprobante

Webhook de causación

Próximos pasos

API documentation

Documentos

Flujos de documentos

Payments

Beneficiaries

Banks

DIAN Events

Fiscal Sync

Registro de facturas en ERPs externos

Guías de Integración

​Arquitectura

​Cerrar el círculo

​Autenticación

​Modelo de identidad

​Orden de carga

​Formato de los endpoints

​Idempotencia

​Bajas y registros inactivos

​Frecuencia

​Salida: el webhook del comprobante

Webhook de causación

​Próximos pasos

Arquitectura

Cerrar el círculo

Autenticación

Modelo de identidad

Orden de carga

Formato de los endpoints

Idempotencia

Bajas y registros inactivos

Frecuencia

Salida: el webhook del comprobante

Próximos pasos