Skip to main content
code<spar>
DocsServersReferenceCookbooksSandbox
ConceptsMeta-tools

codespar_invoice

Fiscal invoices. Default rail NFS-e; opt into NF-e for products, CFDI for Mexico, Factura AR for Argentina.

2 min read
View MarkdownEdit on GitHub

codespar_invoice

Meta-tool

Sell-side. Your agent is the merchant: it collects from, invoices, ships to, or verifies a counterparty.

codespar_invoice issues fiscal documents required by tax authorities across LATAM. Default rail is NFS-e (Brazilian Nota Fiscal de Serviços) — the right pick for SaaS, consulting, and any service-driven flow. Pass rail: "nfe" for product invoices.

Sandbox status

NFS-e issuance is validated against the provider sandbox today; production SEFAZ authorization is on the roadmap.

Issuance is synchronous from the agent's perspective: session.execute() waits for the issuance confirmation before returning. Against production SEFAZ, authorization latency can hit ~2s during peak load. There is no typed wrapper yet — call via session.execute().

Rails

RailCurrencyCountryProviderNotes
nfseBRLBRFiscal API partnerDefault — services. NFS-e tenants can drop the rail field
nfseBRLBRBlingAlternative NFS-e issuer with native ERP/catalog sync
nfeBRLBRFiscal API partnerProducts — requires A1 cert, state tax registration, per-item ICMS classification
nfciMXNMXFacturapiCFDI 4.0 — Mexico
nfciCOPCOSiigoFactura electrónica — Colombia
factura_arARSARAFIPFactura A/B/C — Argentina

Direct execute — services (NFS-e default)

const invoice = await session.execute("codespar_invoice", {
  operation: "create",
  buyer: {
    name: "Maria Silva",
    document: "12345678900", // CPF
    email: "maria@example.com",
  },
  products: [
    {
      description: "SaaS Subscription — Growth Plan",
      quantity: 1,
      unit_price: 49900,
      service_code: "1.05", // Brazilian municipal service code
    },
  ],
  companyId: "cmp_yourFiscalCompanyId",
  metadata: { order_id: "1234" },
});

console.log(invoice.id, invoice.access_key);

Direct execute — products (NF-e)

const invoice = await session.execute("codespar_invoice", {
  rail: "nfe",
  operation: "create",
  buyer: {
    name: "Maria Silva",
    document: "12345678900",
    email: "maria@example.com",
    address: { /* full address required for NF-e */ },
  },
  products: [
    {
      description: "Coffee mug — 350ml",
      quantity: 2,
      unit_price: 4500,
      ncm: "69120000",      // product harmonized code
      cfop: "5102",          // operation code
      icms_origin: "0",      // origin classification (per-item)
    },
  ],
  companyId: "cmp_yourFiscalCompanyId",
});

Args shape

FieldTypeRequiredDescription
railstringNonfse (default), nfe, nfci, factura_ar
operationstringYescreate (today). cancel, correction-letter future
buyerobjectYes{ name, document, email, address? }. NF-e requires address
productsarrayYesLine items. Required tax classification fields differ by rail
companyIdstringYesFiscal-partner company id (or Facturapi/AFIP equivalent) — operator-stamped
metadataobjectNoArbitrary key-value pairs

Result shape

type InvoiceResult = {
  id: string;
  access_key: string;       // neutral name. The BR rail's raw field is `chave`
  number?: number;
  series?: number;
  pdf_url?: string;
  xml_url?: string;
  status: "authorized" | "pending" | "rejected";
  authorized_at?: string;   // ISO 8601
};

access_key is the neutral CodeSpar field; the per-rail raw fields (BR chave, CFDI uuid, Factura AR cae) all normalize into it.

Operator setup

The operator pre-stamps fiscal credentials in /dashboard/auth-configs:

  • NFS-e — fiscal-partner API key + company_id. Service-rail tenants can stop here.
  • NF-e (products) — adds: A1 digital cert (PEM), state tax registration (inscricao_estadual), per-item ICMS / CFOP / NCM classifications. Most operators upload an A1 PFX once in the dashboard; CodeSpar converts to PEM and vaults it.
  • CFDI (Facturapi) — Facturapi API key + RFC.
  • Factura AR (AFIP) — AFIP cert + private key + CUIT.

NF-e issuance targets SEFAZ (Brazil's tax authority) authorization; the flow is validated against the provider sandbox today. Against production SEFAZ, peak-hour latency can hit 2s. A failed authorization comes back as status: "rejected" with the SEFAZ error code on the response — surface that to the operator, do not retry blindly.

See also

Edit on GitHub

codespar_charge

Inbound charges — buyer pays merchant. 19 provider rails — Pix/boleto/card/wallet across BR, MX, PE, CO, CL, AR + USD. Async settlement, uniform payload.

codespar_ship

Domestic shipping. Three rails on Melhor Envio — domestic-label, domestic-quote, domestic-track. Typed wrapper session.ship(args).

On this page

codespar_invoiceRailsDirect execute — services (NFS-e default)Direct execute — products (NF-e)Args shapeResult shapeOperator setupSee also
codespar_invoice | CodeSpar