Skip to main content
Todos os casos de uso
Tesouraria / CartãoOperations

Um cartão vinculado ao mandato, com cada tentativa conferida.

Para as compras avulsas que acabam no cartão pessoal de alguém. O codespar_issue emite o cartão pela Pomelo; a conexão Pomelo aponta para o host de staging da Pomelo. A cada tentativa de cobrança a Pomelo chama o autorizador da CodeSpar, que confere o mandato assinado do agente: validade, moeda, teto por transação, teto total e estabelecimentos permitidos. No modo observe o autorizador registra a decisão e responde aprovado, então uma cobrança que o mandato recusaria passa mesmo assim e fica registrada como exceção. No modo enforce a decisão é a resposta.

AntesUm cartão corporativo compartilhado, revisado semanas depois
DepoisUm cartão por mandato, cada tentativa decidida e registrada
5
conferências em cada tentativa de cobrança
Teste no Sandbox
Pomelo
Emissor
O codespar_issue emite e controla o cartão; a conexão aponta para o host de staging da Pomelo
5
Conferências por tentativa
Validade, moeda, teto por transação, teto total, estabelecimentos permitidos
observe · enforce
Dois modos
Observe registra a decisão e aprova; enforce a torna vinculante
≠
Divergência registrada
No observe, uma cobrança que o mandato recusaria passa e fica registrada como exceção
Exemplo ilustrativo · dados de demonstração

Uma tentativa, uma decisão registrada.

Um exemplo com dados de demonstração: o agente renova uma assinatura com o cartão. A Pomelo consulta o autorizador, que confere o mandato e registra a decisão. No modo observe o emissor recebe aprovado seja qual for a decisão; no modo enforce uma recusa nega a cobrança.

  • O emissor chama o autorizador a cada tentativa; o agente não
  • A decisão confere o mandato: validade, moeda, tetos, estabelecimentos permitidos
  • O modo observe aprova e registra; só o modo enforce nega

Renovar a assinatura de analytics com o cartão de operações.

Cobrando USD 340.00 da SubscriptionCo com o cartão vinculado ao mandato de operações.

Tentativa de autorização de cartão · exemplo
auth_demo · SubscriptionCo
Decisão registrada · exemplo
EstabelecimentoSubscriptionCo · MCC 5817
ValorUSD 340.00
Mandatomnd_demo · USD 2000.00
Decisãowithin_mandate
Resposta ao emissorAPPROVED
authorization-trace.json
✓ decisão registrada · exemploauth_demo
A dor

A conversa é a parte fácil.

Governança de cartão corporativo hoje é um número compartilhado, uma lista de quem pode usar e uma fatura revisada semanas depois. Um agente comprando avulso piora isso: ninguém vê uma cobrança errada antes de ela passar.

Um número de cartão compartilhado para quem precisar comprar

Um cartão vinculado ao mandato assinado do próprio agente

Aprovações depois que a fatura chega

Cada tentativa é decidida contra o mandato na hora

Nenhum registro de por que uma cobrança foi permitida

Cada decisão fica registrada com o motivo

Bloquear um cartão exige ligar para o banco

O codespar_issue congela, descongela ou cancela o cartão no emissor

Como o agente faz isso

Um mandato no cartão, uma decisão a cada tentativa.

O codespar_issue emite e controla o cartão na Pomelo (card-virtual, card-physical, card-control, card-get). A Pomelo chama o autorizador da CodeSpar a cada tentativa; o autorizador encontra o mandato do cartão, confere validade, moeda, teto por transação, teto total e estabelecimentos permitidos, e registra a decisão. Se essa decisão vale depende do modo: no observe ela é registrada e o emissor recebe aprovado; no enforce ela é a resposta.

01
Emitir
codespar_issue

Um cartão vinculado ao mandato

codespar_issue
02
Tentativa
Pomelo

Um estabelecimento cobra o cartão

03
Conferir
Autorizador

Validade, moeda, tetos, estabelecimentos

04
Responder
Autorizador

Observe: aprovado · enforce: a decisão

05
Registrar
Trilha de auditoria

Decisão e motivo registrados

Arquitetura

A Pomelo assina cada pedido de autorização para POST /v1/webhooks/pomelo/authorize. A rota verifica a assinatura; o núcleo compartilhado encontra o mandato do cartão, decide (validade, moeda, teto por transação, teto total, estabelecimentos permitidos por MCC ou id do estabelecimento), persiste a decisão e a sela na trilha de auditoria. No modo observe o emissor recebe aprovado e uma decisão que o mandato recusaria fica registrada como exceção; no modo enforce a decisão é a resposta. Uma pausa da organização vai como recusa em qualquer modo, quando o emissor espera a resposta.

Em código

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

governed-agent-card.ts
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…), a Pomelo
// connection (it points at Pomelo's staging host) and a card already issued to
// the agent (card_id). The authorizer is not called from here: Pomelo calls it
// on every charge attempt.
import { CodeSpar } from "@codespar/sdk";

const session = await new CodeSpar().create("user_0000", { preset: "brazilian" });

// read the card at the issuer
const card = await session.execute("codespar_issue", { action: "card-get", card_id: "crd_demo" });
console.log(card.data);

// freeze it at the issuer, for instance when the agent is paused
await session.execute("codespar_issue", { action: "card-control", card_id: "crd_demo", control: "freeze", reason: "agent paused" });

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_issue

Emite cartões virtuais ou físicos na Pomelo, consulta, e congela, descongela ou cancela.

POST /v1/webhooks/pomelo/authorize

O autorizador que o emissor chama a cada tentativa; o agente nunca o chama.

Mandate

Validade, moeda, tetos por transação e total, e os estabelecimentos permitidos que o autorizador confere.

Ver a referência das meta-tools
Servidores MCP conectados

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.

Cartão governado do agente — CodeSpar | CodeSpar