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

codespar_invoice

Meta-tool

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

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

Rails

Rail	Currency	Country	Provider	Notes
`nfse`	BRL	BR	NFe.io	Default — services. NFS-e tenants can drop the `rail` field
`nfe`	BRL	BR	NFe.io	Products — requires A1 cert, state tax registration, per-item ICMS classification
`nfci`	MXN	MX	Facturapi	CFDI 4.0 — Mexico
`factura_ar`	ARS	AR	AFIP	Factura 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_yourNFeIoCompanyId",
  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_yourNFeIoCompanyId",
});

Args shape

Field	Type	Required	Description
`rail`	`string`	No	`nfse` (default), `nfe`, `nfci`, `factura_ar`
`operation`	`string`	Yes	`create` (today). `cancel`, `correction-letter` future
`buyer`	`object`	Yes	`{ name, document, email, address? }`. NF-e requires `address`
`products`	`array`	Yes	Line items. Required tax classification fields differ by rail
`companyId`	`string`	Yes	NFe.io company id (or Facturapi/AFIP equivalent) — operator-stamped
`metadata`	`object`	No	Arbitrary key-value pairs

Result shape

type InvoiceResult = {
  id: string;
  access_key: string;       // neutral name. NFe.io'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 (NFe.io chave, CFDI uuid, Factura AR cae) all normalize into it.

Operator setup

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

NFS-e — NFe.io 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 communicates with SEFAZ (Brazil's tax authority) in real time. During peak hours 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.

codespar_invoice

codespar_invoice

Rails

Direct execute — services (NFS-e default)

Direct execute — products (NF-e)

Args shape

Result shape

Operator setup

See also

On this page