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

import { Callout } from "fumadocs-ui/components/callout";

# codespar_invoice

<Callout title="Meta-tool" type="info">
**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.
</Callout>

<Callout title="Sandbox status" type="warn">
NFS-e issuance is validated against the provider sandbox today; production SEFAZ authorization is on the roadmap.
</Callout>

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

| Rail | Currency | Country | Provider | Notes |
|---|---|---|---|---|
| `nfse` | BRL | BR | Fiscal API partner | Default — services. NFS-e tenants can drop the `rail` field |
| `nfse` | BRL | BR | Bling | Alternative NFS-e issuer with native ERP/catalog sync |
| `nfe` | BRL | BR | Fiscal API partner | Products — requires A1 cert, state tax registration, per-item ICMS classification |
| `nfci` | MXN | MX | Facturapi | CFDI 4.0 — Mexico |
| `nfci` | COP | CO | Siigo | Factura electrónica — Colombia |
| `factura_ar` | ARS | AR | AFIP | Factura A/B/C — Argentina |

## Direct execute — services (NFS-e default)

```ts
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)

```ts
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

| 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 | Fiscal-partner company id (or Facturapi/AFIP equivalent) — operator-stamped |
| `metadata` | `object` | No | Arbitrary key-value pairs |

## Result shape

```ts
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.

<Callout type="warn">
NF-e issuance targets [SEFAZ](/docs/glossary) (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.
</Callout>

## See also

- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list
- [E-Commerce Checkout cookbook](/docs/cookbooks/ecommerce-checkout) — charge → invoice → ship → notify
- [Webhook Listener cookbook](/docs/cookbooks/webhook-listener) — issue invoice from a settlement event
- [Glossary](/docs/glossary) — SEFAZ, NF-e, NFS-e, CFDI definitions