Skip to main content
Todos os casos de uso
Folha + pagamentosOperations

O dia de pagamento como um laço sobre a sua lista aprovada.

O agente lê a lista de prestadores que o seu time aprovou e paga cada favorecido por Pix com o codespar_pay: para uma chave Pix, ou para dados bancários quando o favorecido não tem chave. Cada transferência leva a sua própria chave de idempotência, então uma nova tentativa devolve o primeiro resultado em vez de pagar de novo. Conferir chaves e documentos antes da rodada e conciliá-la no ERP são a parte dos seus sistemas.

AntesArquivo CNAB → portal do banco → corrigir as rejeições
DepoisSua lista aprovada → um Pix por favorecido
1 Pix
por prestador da lista aprovada
Teste no Sandbox
Pix
Rail de pagamento
Pix para uma chave, ou para dados bancários quando não há chave
1:1
Um por favorecido
Uma chamada ao codespar_pay por prestador da lista
idempotency_key
Sem segundo pagamento
Uma nova tentativa com a mesma chave devolve o primeiro resultado
ERP
Seu ERP
A lista vem dele e a rodada fecha nele, pela sua integração
Exemplo ilustrativo · dados de demonstração

Uma rodada, uma transferência por favorecido.

Um exemplo com dados de demonstração: a rodada de junho, lida da lista aprovada e paga por Pix, uma transferência por prestador, cada uma com a sua chave de idempotência.

  • A lista é a que o seu time aprovou
  • Um Pix por prestador, cada um com a sua chave de idempotência
  • Conciliar a rodada no ERP é a sua integração

Rodar o pagamento de prestadores de junho a partir da lista aprovada.

24 prestadores na lista aprovada: pagando cada um por Pix, uma transferência por favorecido.

Rodada de pagamento · exemplo
RUN-06 · 24
Pago · exemplo
TotalR$ 96.400,00
Favorecidos24
RailPix · 24
Chave de idempotênciapayroll-2026-06-<id>
run-06.csv
✓ pago · exemploRUN-06
A dor

A conversa é a parte fácil.

Pagar prestadores na América Latina é um ritual mensal: exportar uma planilha, gerar um arquivo CNAB, subir no portal do banco, corrigir as rejeições e conciliar à mão. Funciona até o mesmo arquivo subir duas vezes.

Montar um arquivo CNAB e subir no portal do banco todo mês

O agente paga a lista aprovada por Pix, uma transferência por favorecido

Subir o mesmo arquivo duas vezes e pagar duas vezes

Cada transferência tem uma chave de idempotência; uma nova tentativa devolve o primeiro resultado

Favorecidos sem chave Pix exigem outro processo

O codespar_pay também paga para dados bancários quando não há chave

Procurar cada transferência no portal do banco

O codespar_pay action=status lê cada pagamento pelo id

Como o agente faz isso

Uma chamada por favorecido, por Pix.

Para cada prestador da lista aprovada, o agente chama o codespar_pay com method pix, a chave do favorecido (ou os dados bancários), o valor em centavos e uma chave de idempotência. A action=status lê cada pagamento depois. A lista aprovada, qualquer conferência de chaves e documentos antes da rodada e a conciliação no seu ERP são a sua integração.

01
Lista
Seu ERP ou planilha

Prestadores aprovados

02
Pagar
codespar_pay

Um Pix por favorecido

codespar_pay
03
Nova tentativa
idempotency_key

Mesma chave, primeiro resultado

04
Status
codespar_pay

Cada pagamento pelo id

codespar_pay
05
Conciliar
Sua integração

A rodada no seu ERP

Arquitetura

A lista aprovada entra pelo seu ERP ou por uma planilha. O agente percorre a lista e chama o codespar_pay uma vez por favorecido: Pix para uma chave, ou para dados bancários quando o favorecido não tem chave. A chave de idempotência amarra uma nova tentativa à primeira. O status de cada pagamento é lido pelo id. Conferir os favorecidos antes da rodada e escrever a rodada de volta no ERP são feitos pelos seus sistemas, não pela CodeSpar.

Em código

O código, e o que ele pressupõe.

contractor-payroll.ts
// 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);
}

Exemplo com o SDK publicado (@codespar/sdk 0.16.11). Os pré-requisitos estão nos comentários. Compilar não prova a integração: rode primeiro em modo de teste.

Ferramentas em destaque
codespar_pay

Paga um Pix por favorecido, para uma chave ou dados bancários; a idempotency_key evita um segundo pagamento numa nova tentativa; a action=status consulta.

Ver a referência das meta-tools

Comece com uma chave de teste.

Chaves de teste são gratuitas. Abra o sandbox, conecte os provedores que o seu projeto usa e veja quais ferramentas ele pode chamar antes de construir.

Agente de pagamento de prestadores — CodeSpar | CodeSpar