Invoice Emission

Table: accounting_invoices. One row per NFS-e request.

Core fields

• Type — services | products.
• Status — see the lifecycle below.
• SellerId — the SellerFiscalEntity id.
• BuyerId — optional BuyerFiscalEntity id.
• FiscalDate — "YYYY-MM-DD".
• Amount — in cents (integer). 1000 = R$ 10,00.
• ItemsSource — checkout | bill | manual.

Collections

• Items[] — line items (description, quantity, unit price, total).
• Taxes[] — tax items with percentages.
• Partners[] — commission splits (for marketplace flows).

Sub-documents

• Emissions — JSONB column, one per attempt. Each entry has status, provider, providerId, providerErrors, providerStatuses (history), and providerRequest (the full payload sent).
• Data — provider-issued data: number, code, emission_date, cancelation_date.
• Urls — pdf and xml download links.
• Callback — optional routing targets for async notification callbacks: {service, controller, action, validation_id}.

Two parallel state machines: the invoice status and the emission status.

Invoice status

Cancellation branch

Emission status (sub-document)

An emission can only be canceled when its status is authorized.

NFS-e requirements vary by municipality. The emission pipeline handles city-specific formatting automatically for the supported cities:

Rio de Janeiro, Taboão da Serra, Vitória da Conquista, Andradas, Santana de Parnaíba, Caxias do Sul, Sobral, Cabo Frio, São Paulo, Osasco + a Default fallback.

POST /fiscal-entities/:id/invoices/:invoice_id/cancel begins the cancellation flow.

Flow

1. The system validates that the invoice is not already canceled.
2. Sets the invoice status to pending-cancelation immediately.
3. If the seller's emission_status is inactive, the cancellation completes without contacting the provider.
4. Otherwise cancels with the provider and sets the emission to requested-cancelation.
5. Sets the invoice status to requested-cancelation.
6. The provider callback or the safety-net worker resolves the final state: canceled or failed-cancelation.

A safety-net worker polls every 2 minutes as a fallback to recover from missed callbacks. This means that even if a callback is lost, the invoice will still resolve to a final state within 2 minutes.

When an invoice has a Callback set (the requester passed one in POST /invoices), every status change fires a notification to that callback target. The routing is stored on the invoice as {service, controller, action}.

Events fired

Each event also appends a Calls history entry on the invoice with the timestamp, status, and metadata.

Create invoice request

POST /fiscal-entities/123/invoices
{
  "data": {
    "type": "invoices",
    "attributes": {
      "fiscal-date": "2024-10-15",
      "items-source": "manual",
      "items": [
        { "description": "Manicure", "quantity": 1, "unit-price": 5000 }
      ],
      "options": { "notes": ["Cliente VIP"] },
      "callback": { "service": "business", "controller": "invoices", "action": "process_callback" }
    }
  }
}

Invoice response

{
  "data": {
    "id": "123456",
    "type": "invoices",
    "attributes": {
      "reference-key": "1234-01-1734...",
      "type": "services",
      "status": "pending",
      "fiscal-date": "2024-10-15",
      "amount": 5000,
      "items-source": "manual",
      "items": [...],
      "taxes": [],
      "partners": [],
      "data": { "number": null, "code": null, "emission_date": null, "cancelation_date": null },
      "urls": { "pdf": null, "xml": null },
      "options": { "notes": [] },
      "extra": {}
    },
    "relationships": {
      "seller": { "data": { "type": "fiscal-entities", "id": "123" } },
      "buyer":  { "data": null }
    }
  }
}

Once the invoice reaches succeeded, data and urls are populated with the provider-issued data and download links.

In staging, emission is simulated without contacting the provider. In production, invoices are emitted with the real provider.