DAS Emission · Contabeleza API Docs

Endpoints

Method	Path	Purpose
GET	`/fiscal-entities/:id/mei/das`	List DAS for a fiscal entity. Query params: `?year=YYYY`, `?month=MM`.
PATCH	`/fiscal-entities/:id/mei/das`	Force-refresh DAS data. Same query params; ignores cache.
GET	`/fiscal-entities/:id/mei/das/pdf?year=YYYY&month=MM`	Get the official PDF boleto for a specific month.
POST	`/fiscal-entities/:id/mei/das/notify`	Send the DAS PDF link to the user by email (via `notifier` service).
GET	`/fiscal-entities/mei/das`	Accountant view — list DAS for all MEIs under a partner's businesses.
PATCH	`/fiscal-entities/mei/das`	Accountant batch update.

Providers

The system has two providers, selected by the strategy layer based on how many months are pending.

Serpro (synchronous, single-month)

Official government API. Used to generate the official DAS PDF and fetch the barcode/Pix code for a single month synchronously.

InfoSimples (asynchronous, bulk)

3rd-party scraper of the Receita Federal site. Used to fetch the list of DAS for a given year asynchronously — the request returns immediately and the data arrives via a callback later.

Strategy selection

The system selects a provider based on how many months are pending:

pending ≤ 3 months

→

Serpro sync, one by one

pending > 3 months

→

InfoSimples async, whole year

Full flow — from request to delivered boleto

client

Sends GET /fiscal-entities/:id/mei/das?year=2024 (or PATCH to force refresh).

accounting

Resolves the fiscal entity and its stored DAS data.

accounting

Selects the strategy based on pending month count. For PATCH, marks months as requested and fires provider calls.

accounting → Serpro

Sync path: returns the official DAS payload (PDF + barcode + Pix) for a single month.

accounting → InfoSimples

Async path: fires the request and returns immediately; results arrive via callback.

accounting

Maps provider responses to DAS status: already_paid → paid, payment_not_available → waiting-payment, in_active_debt → in-active-debt, not_mei → not-mei, else → errored.

accounting

Stores the result and returns the JSON:API response.

Status enum

9 status values, one per month:

Status	Meaning
`not-requested`	Month not yet consulted.
`requested`	Provider call fired; awaiting response.
`not-mei`	MEI was not active that month — no DAS to pay.
`failed`	Boleto not paid or not found.
`waiting-payment`	Boleto generated, not yet paid.
`paid`	Boleto paid. ✅
`missing`	No data for the month (not yet requested).
`in-active-debt`	Boleto sent to divida ativa.
`errored`	Provider call failed. Retried after 12h.

Flow per month

not-requested

→

requested

→

waiting-payment

→

paid

JSON:API shape

{
  "data": {
    "id": "123.456.01.202410",
    "type": "fiscal-entity-mei-das",
    "attributes": {
      "key": "202410",
      "status": "waiting-payment",
      "updated-at": "2024-10-15T12:00:00Z",
      "details": {
        "periodoApuracao": "202410",
        "numeroDocumento": "07.40.12345.0123456-7",
        "dataVencimento": "20241020",
        "valores": { "principal": 71.60, "multa": 0, "juros": 0, "total": 71.60 },
        "composicao": [...],
        "codigoDeBarras": [...]
      },
      "extra": {
        "pdf-url":   "https://assets..../das202410_emp_xyz.pdf",
        "pix-url":   "https://assets..../das202410_emp_xyz_qrcode.png",
        "pix-text":  "00020126...",
        "pdf-exp-date": "2024-10-20"
      }
    }
  }
}

The system rewrites extra.pdf-url and extra.pix-url to public asset URLs with an expiration date (typically the boleto's due date).

PDF & Pix generation

The PDF generation flow:

Check if a cached PDF exists in storage and is < 1 day old.
If stale (or missing), call Serpro to generate the PDF.
Receive the base64 PDF and extract the Pix QR code from it.
Upload both to the mei/{meiId}/das/ bucket prefix.
Store the public URLs in extra.pdf-url, extra.pix-url, and the Pix BR Code in extra.pix-text.
Return the rewritten URLs to the client.

Cache TTL: 1 day. After that, the next request regenerates the PDF to ensure freshness.

Accountant / partner view

For partners that manage multiple MEIs (e.g. an accounting firm), the partners controller exposes batch endpoints:

GET /fiscal-entities/mei/das — returns the DAS for all MEIs under the partner's businesses, in one response.
PATCH /fiscal-entities/mei/das — triggers a batch update.

The system iterates all owned fiscal entities, processes each one, and concatenates the results.