codespar_invoice

Actions

Example

action: "issue" of an NFS-e (a service invoice), the default action.

{
  "name": "codespar_invoice",
  "arguments": {
    "type": "nfse",
    "action": "issue",
    "recipient": {
      "name": "Example Buyer",
      "document": "00000000000",
      "email": "buyer@example.com"
    },
    "items": [
      {
        "description": "Example service",
        "quantity": 1,
        "unit_price": 10000
      }
    ]
  }
}

const result = await session.execute("codespar_invoice", {
  type: "nfse",
  action: "issue",
  recipient: {
    name: "Example Buyer",
    document: "00000000000",
    email: "buyer@example.com"
  },
  items: [
    {
      description: "Example service",
      quantity: 1,
      unit_price: 10000
    }
  ]
});

result = session.execute("codespar_invoice", {
  "type": "nfse",
  "action": "issue",
  "recipient": {
    "name": "Example Buyer",
    "document": "00000000000",
    "email": "buyer@example.com"
  },
  "items": [
    {
      "description": "Example service",
      "quantity": 1,
      "unit_price": 10000
    }
  ]
})

codespar tool codespar_invoice \
  -i '{
       "type": "nfse",
       "action": "issue",
       "recipient": {
         "name": "Example Buyer",
         "document": "00000000000",
         "email": "buyer@example.com"
       },
       "items": [
         {
           "description": "Example service",
           "quantity": 1,
           "unit_price": 10000
         }
       ]
     }'

When to use

• Services (SaaS, consulting, anything service-driven): type: "nfse", the Brazilian Nota Fiscal de Serviços.
• Products: type: "nfe". Issuance needs the operator's A1 certificate, state tax registration and per-item ICMS classification stamped in the dashboard first (see Notes).
• Outside Brazil: type: "nfci", the consumer-invoice rail. It routes by country to Facturapi for the Mexican CFDI 4.0, AFIP for the Argentine Factura A/B/C, and Siigo for the Colombian factura electrónica. Connect the provider for your country first.
• After a settlement: the usual chain is charge → wait for settlement → invoice → ship → notify. The Webhook Listener cookbook issues the invoice from the settlement event.
• Reading or correcting: status reads the fiscal state by invoice_id; amend writes a correction letter (CC-e) while the SEFAZ amendment window is open, or cancels and reissues as a substitute (tipo 3) once it is not, and the result says which applied.

Arguments

Errors and what to do

Money and mandate

No money moves on this tool. It emits, reads and amends fiscal documents, which are irreversible acts with the tax authority: an authorized NF-e can be corrected or cancelled and reissued, never silently replaced. There is no mandate gate on issuance; the operator's fiscal credentials (see Notes) are what authorize it, so an agent that can reach this tool can issue documents in the operator's name. Keep the action value exact (see the warning at the top).

Related

• codespar_charge: the settlement that usually precedes the invoice
• codespar_ship and codespar_notify: the next steps in the sell-side chain
• E-Commerce Checkout cookbook: charge → invoice → ship → notify
• Webhook Listener cookbook: issue the invoice from a settlement event
• Glossary: SEFAZ, NF-e, NFS-e, CFDI

Notes

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

Rails, measured 2026-09-11 against the catalog. nfse routes to the fiscal partner or Bling (BRL, BR). nfe routes to the fiscal partner (BRL, BR; needs the A1 certificate, state tax registration and per-item ICMS classification). nfci is the one that answers the question this paragraph used to leave open: it carries all three non-Brazilian lines, selected by country — Facturapi for CFDI 4.0 (MXN, MX), AFIP for Factura A/B/C (ARS, AR), Siigo for factura electrónica (COP, CO).

The earlier page named type: "invoice" for Stripe Invoicing. There is no catalog line for that value, so it came back eligibility_empty for every tenant while nfci, which works, went unmentioned. The dead value is recorded in the API repository (ent#1280).

Operator setup. The operator pre-stamps fiscal credentials in /dashboard/auth-configs: NFS-e needs the fiscal partner's API key and company id (service-rail tenants can stop here); NF-e adds the A1 digital certificate (most operators upload a PFX once and CodeSpar converts it to PEM and vaults it), the state tax registration (inscricao_estadual) and per-item ICMS / CFOP / NCM classifications; CFDI needs the Facturapi key and RFC; Factura AR needs the AFIP certificate, private key and CUIT.

Result shape (SDK), as previously documented. { id, access_key, number?, series?, pdf_url?, xml_url?, status: "authorized" | "pending" | "rejected", authorized_at? }, where access_key is the neutral field the per-rail raw keys (BR chave, CFDI uuid, Factura AR cae) normalize into. This revision did not re-verify that list against the runtime.

From the SDK. There is no typed wrapper; call session.execute("codespar_invoice", arguments) with the same arguments as the MCP call. The dispatch also accepts buyer for recipient and products for items; the schema names recipient and items, so use those.