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 }
    ]
  }
}

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: "invoice" routes to Stripe Invoicing.
• 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, as previously documented. The earlier page listed the fiscal partner and Bling for NFS-e (BRL, BR), the fiscal partner for NF-e (BRL, BR; needs A1 cert, state tax registration, per-item ICMS), Facturapi for CFDI 4.0 (MXN, MX), Siigo for factura electrónica (COP, CO) and AFIP for Factura A/B/C (ARS, AR). The published schema names only three type values (nfe, nfse, invoice), so how the Mexican, Colombian and Argentine rails are selected is not documented by the schema; this revision did not re-verify those lines.

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.