El día de pago como un ciclo sobre tu lista aprobada.
El agente lee la lista de contratistas que aprobó tu equipo y le paga a cada beneficiario por Pix con codespar_pay: a una clave Pix, o a datos bancarios cuando el beneficiario no tiene clave. Cada transferencia lleva su propia clave de idempotencia, así un reintento devuelve el primer resultado en lugar de pagar de nuevo. Revisar claves y documentos antes de la corrida y conciliarla en tu ERP son la parte de tus sistemas.
Una corrida, una transferencia por beneficiario.
Un ejemplo con datos de demostración: la corrida de junio, leída de la lista aprobada y pagada por Pix, una transferencia por contratista, cada una con su propia clave de idempotencia.
- La lista es la que aprobó tu equipo
- Un Pix por contratista, cada uno con su propia clave de idempotencia
- Conciliar la corrida en el ERP es tu integración
Correr la nómina de contratistas de junio desde la lista aprobada.
24 contratistas en la lista aprobada: pagándole a cada uno por Pix, una transferencia por beneficiario.
La conversación es la parte fácil.
Pagar a contratistas en LATAM es un ritual mensual: exportar una planilla, generar un archivo CNAB, subirlo al portal del banco, corregir los rechazos y conciliar a mano. Funciona hasta que el mismo archivo se sube dos veces.
Armar un archivo CNAB y subirlo al portal del banco cada mes
El agente paga la lista aprobada por Pix, una transferencia por beneficiario
Subir el mismo archivo dos veces y pagar dos veces
Cada transferencia tiene una clave de idempotencia; un reintento devuelve el primer resultado
Los beneficiarios sin clave Pix requieren otro proceso
codespar_pay también paga a datos bancarios cuando no hay clave
Buscar cada transferencia en el portal del banco
codespar_pay action=status lee cada pago por su id
Una llamada por beneficiario, por Pix.
Para cada contratista de la lista aprobada, el agente llama a codespar_pay con method pix, la clave del beneficiario (o sus datos bancarios), el monto en centavos y una clave de idempotencia. action=status lee cada pago después. La lista aprobada, cualquier revisión de claves y documentos antes de la corrida y la conciliación en tu ERP son tu integración.
Contratistas aprobados
codespar_payUn Pix por beneficiario
codespar_payMisma clave, primer resultado
codespar_payCada pago por su id
codespar_payLa corrida en tu ERP
La lista aprobada entra desde tu ERP o una planilla. El agente la recorre y llama a codespar_pay una vez por beneficiario: Pix a una clave, o a datos bancarios cuando el beneficiario no tiene clave. La clave de idempotencia ata un reintento al primer intento. El estado de cada pago se lee por su id. Revisar a los beneficiarios antes de la corrida y escribir la corrida de vuelta en el ERP lo hacen tus sistemas, no CodeSpar.
El código, y lo que supone.
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…) and a Pix // provider connected to the project. The approved list comes from your systems. import { CodeSpar } from "@codespar/sdk"; const session = await new CodeSpar().create("ops_payroll", { preset: "brazilian" }); const approved = [ { id: "c-001", name: "Ana Souza", pixKey: "ana@example.com", amountMinor: 420_000 }, { id: "c-002", name: "Bruno Lima", pixKey: "+5511999990000", amountMinor: 380_000 }, ]; for (const c of approved) { const res = await session.execute("codespar_pay", { action: "pay", method: "pix", recipient: c.pixKey, amount: c.amountMinor, // centavos currency: "BRL", description: `June payroll · ${c.name}`, idempotency_key: `payroll-2026-06-${c.id}`, // a retry returns the first result }); console.log(c.id, res.success); }
Ejemplo con el SDK publicado (@codespar/sdk 0.16.11). Los requisitos están en los comentarios. Compilar no prueba la integración: ejecútalo primero en modo de prueba.
codespar_payPaga un Pix por beneficiario, a una clave o datos bancarios; idempotency_key evita un segundo pago en un reintento; action=status lo consulta.
Empieza con una clave de prueba.
Las claves de prueba son gratuitas. Abre el sandbox, conecta los proveedores que usa tu proyecto y mira qué herramientas puede llamar antes de construir.