Fiscal Operations

Emit the DAS for a competência and record it as a GUIA

Emit the DAS for a transmitted competência through the tenant's bound fiscal provider, and record it as a `GUIA` fiscal document (born `EMITIDO`).

References only: the response and the document carry the guia's number, due date, amounts and the PDF's sha256 — never the PDF.

Requires an `Idempotency-Key` header; a retry on the same key writes the guia once.

Raises: 404: ACCOUNT_NOT_FOUND 409: FISCAL_NOT_AUTHORIZED, IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, FISCAL_REJECTED (e.g. NO_DECLARATION, BELOW_MINIMUM_DEBIT) 503: FISCAL_PROVIDER_UNAVAILABLE, FISCAL_BINDING_BROKEN

Parâmetros

Corpo da requisição

DasEmissionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Cancel an authorised NFS-e with the emitente's signature

Submit the signed cancellation. The note lands `CANCELADA`; a refusal — the município's deadline passed (`CANCEL_WINDOW_CLOSED`), or the note is already closed — leaves it `AUTORIZADA`.

Raises: 404: ACCOUNT_NOT_FOUND, FISCAL_DOCUMENT_NOT_FOUND 409: FISCAL_DOCUMENT_STATE, IDEMPOTENCY_KEY_REUSED 422: FISCAL_REJECTED (SIGNER_NOT_EMITTER, SIGNATURE_INVALID, CANCEL_WINDOW_CLOSED, NFSE_ALREADY_CLOSED), FISCAL_OPERATION_NOT_SUPPORTED 503: FISCAL_PROVIDER_UNAVAILABLE, FISCAL_BINDING_BROKEN

Parâmetros

Corpo da requisição

NfseCancellationRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Prepare the cancellation of an authorised NFS-e for the emitente to sign

Build the cancellation event (e101101) of an authorised note and answer its `signing_request`, plus the `dh_evento` to send back on submission. The deadline is the município's, enforced by the platform when the event is submitted.

Raises: 404: ACCOUNT_NOT_FOUND, FISCAL_DOCUMENT_NOT_FOUND 409: FISCAL_DOCUMENT_STATE, IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, FISCAL_REJECTED (INVALID_REQUEST), INVALID_COMPETENCIA, INVALID_SERIE, SUBSTITUTION_REASON_REQUIRED, or a validation error 503: FISCAL_PROVIDER_UNAVAILABLE, FISCAL_BINDING_BROKEN

Parâmetros

Corpo da requisição

NfseCancellationPreparationRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Prepare an NFS-e for the emitente to sign

Build the note's DPS and answer a `signing_request` — the canonical SignedInfo bytes and the algorithm — for the **emitente's own device** to sign. The note is recorded as an `NFSE` fiscal document in `AGUARDANDO_ASSINATURA`.

Nothing is sent to the platform yet. Pass `doc_id` to prepare a draft or a rejected note again (it keeps its DPS number); pass `replaces` and `substituicao` to prepare a note that substitutes an authorised one.

Raises: 404: ACCOUNT_NOT_FOUND, FISCAL_DOCUMENT_NOT_FOUND 409: FISCAL_DOCUMENT_STATE, IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, FISCAL_REJECTED (INVALID_REQUEST), INVALID_COMPETENCIA, INVALID_SERIE, SUBSTITUTION_REASON_REQUIRED, or a validation error 503: FISCAL_PROVIDER_UNAVAILABLE, FISCAL_BINDING_BROKEN

Parâmetros

Corpo da requisição

NfsePreparationRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Submit a prepared NFS-e with the emitente's signature

Submit a prepared note with the `SignatureValue` and certificate the emitente's device produced. Before anything is sent the signature is verified, the certificate is checked to be the emitente's own, and the DPS is regenerated from `dps` and must be the one prepared. An authorised note lands `AUTORIZADA` with its 50-digit chave.

⭐ **Safe to retry.** The DPS Id is the platform's own uniqueness key: before every send the provider is asked whether a note already exists for it, and if one does, the answer is that note. If it exists and its chave cannot be read back, the answer is `outcome_unknown` — terminal, never a resend.

Raises: 404: ACCOUNT_NOT_FOUND, FISCAL_DOCUMENT_NOT_FOUND 409: FISCAL_DOCUMENT_STATE, CHAVE_CONFLICT, IDEMPOTENCY_KEY_REUSED 422: FISCAL_REJECTED — ours, before any call (SIGNER_NOT_EMITTER, SIGNATURE_INVALID, CERTIFICATE_EXPIRED, DOCUMENT_CHANGED), or the platform's (the note lands REJEITADA); FISCAL_OPERATION_NOT_SUPPORTED 503: FISCAL_PROVIDER_UNAVAILABLE (retryable, Retry-After), FISCAL_BINDING_BROKEN or reason_code outcome_unknown (not retryable)

Parâmetros

Corpo da requisição

NfseSubmissionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

List the PGDAS-D declarations transmitted in an ano-calendário

The index of one ano-calendário's PGDAS-D declarations, per período: `data.periodos[{competencia, declaracoes[{numero_declaracao, tipo (original|retificadora), transmitida_em, malha}], das[...]}]`. A proven-empty year is served with `data.found: false`.

⛔ An index, never the content: no receita bruta, no folha, no PDF. It tells the activation trail (contabil-14) which months were declared; the values stay the client's to declare.

⚠️ Billed on every call. Requires an `Idempotency-Key`.

Raises: 404: ACCOUNT_NOT_FOUND 409: FISCAL_NOT_AUTHORIZED, IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, FISCAL_REJECTED, or a validation error (a year before 2018) 503: FISCAL_PROVIDER_UNAVAILABLE, FISCAL_BINDING_BROKEN

Parâmetros

Corpo da requisição

PgdasDeclarationsQueryRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Transmit the PGDAS-D for a competência

Transmit the month's PGDAS-D through the tenant's bound fiscal provider.

⭐ **Idempotent on the período, not only on the key.** Before every send the provider is asked whether the período already has a declaration; if it does, the answer is that declaration (`data.replayed: true`) and nothing is filed. A retificação is explicit: name the declaration it corrects in `retifica_numero`.

Requires an `Idempotency-Key` header. Only a 201 is cached, so an outage stays retryable on the same key.

Raises: 404: ACCOUNT_NOT_FOUND 409: FISCAL_NOT_AUTHORIZED (the contribuinte has not authorised us — no Retry-After), IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, FISCAL_REJECTED, or a validation error 503: FISCAL_PROVIDER_UNAVAILABLE (retryable, Retry-After), FISCAL_BINDING_BROKEN (not retryable)

Parâmetros

Corpo da requisição

PgdasTransmissionRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Ask whether the contribuinte has granted the procuração in the e-CAC

Ask the tenant's bound fiscal provider whether the contribuinte has granted the firm a procuração in the e-CAC for every code in `required_codes` (default `00146`, PGDAS-D). Served: `data.granted`, `data.codes`, `data.expires_on`. There is no grant operation — the client grants it in the e-CAC, and this is how the return is detected (contabil-14).

⚠️ **Billed on every call, a refusal included.** A POST because it costs money. Only a 201 is cached on the key, so send a fresh `Idempotency-Key` per check — a reused one replays the first answer.

Raises: 404: ACCOUNT_NOT_FOUND 409: FISCAL_NOT_AUTHORIZED (no procuração yet — no Retry-After: only the client resolves it), IDEMPOTENCY_KEY_REUSED 422: FISCAL_PROVIDER_UNKNOWN, FISCAL_OPERATION_NOT_SUPPORTED, or a validation error 503: FISCAL_PROVIDER_UNAVAILABLE (retryable, Retry-After), FISCAL_BINDING_BROKEN (not retryable)

Parâmetros

Corpo da requisição

ProcuracaoQueryRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas