Referência / Quadra Command API
Attestations
1 operação em Quadra Command API 0.2.0.
/v1/attestationsRecord a CRC professional's attestation of one accounting artifact
Record that a CRC-holding professional attested one artifact: a closed period (`PERIOD` — `COMPETENCIA_APROVADA`, `CARTA_RESPONSABILIDADE`), the closed month's complete export box (`PIECE` — `ESCRITURACAO_ASSINADA`), or a fiscal document (`FISCDOC` — `ESCRITURACAO_ASSINADA`).
⭐ **`subject_hash` must be the artifact's hash now.** Send the `current_subject_hash` from the artifact's own read; if the artifact changed since, the answer is 409 `SUBJECT_HASH_MISMATCH` and nothing is written — a stale screen can never be signed.
⭐ **Anchored in the ledger.** The record's digest is committed to the journal hash chain in the same transaction (`journal_seq_no`), so it is sealed by the next signed checkpoint and cannot be edited or removed without detection.
⛔ **One subject per request.** There is no batch form (Phase-0 P2: the act is personal and privative). A reclassification is attested on `PATCH /v1/obligations/{id}/natureza`, beside the correction itself.
Raises: 404: SUBJECT_NOT_FOUND (unknown and foreign subjects are the same miss) 409: SUBJECT_HASH_MISMATCH, IDEMPOTENCY_KEY_REUSED, ATTESTATION_CONFLICT 422: NOT_ATTESTABLE (e.g. the period is not CLOSED), ACT_NOT_ALLOWED_FOR_SUBJECT, INVALID_ATTESTATION, INVALID_SUBJECT_ID 503: JOURNAL_NOT_STARTED
Parâmetros
| Nome | Tipo | Detalhe |
|---|---|---|
| Idempotency-Key | string | headerobrigatório |
Corpo da requisição
CreateAttestationRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.
Respostas
| Status | Corpo | Detalhe |
|---|---|---|
| 201 | AttestationRecord | Resposta bem-sucedida |
| 422 | HTTPValidationError | Erro de validação |
Esquemas
Os modelos que as operações acima aceitam e devolvem. Campos opcionais estão marcados como tal; um campo tipado como outro modelo está documentado sob o nome dele.
AttestationRecord
One CRC professional's act on one artifact.
| Campo | Tipo | Detalhe |
|---|---|---|
| act | string | obrigatórioESCRITURACAO_ASSINADA | COMPETENCIA_APROVADA | RECLASSIFICACAO | CARTA_RESPONSABILIDADE | REABERTURA_AUTORIZADA |
| attestation_version | integer | obrigatório |
| attested_at | string | obrigatórioServer clock at the write (UTC) |
| attested_via | string | obrigatórioThe surface the act was performed on |
| crc_number | string | obrigatórioThe professional's CRC registration |
| crc_uf | string | obrigatórioThe UF of that registration |
| firm_cnpj | string | obrigatórioThe organização contábil — the contracting party |
| firm_crc | string | obrigatórioThe firm's own CRC registration |
| journal_hash | string | obrigatórioThat entry's journal_hash |
| journal_seq_no | integer | obrigatórioThe journal entry that commits record_digest |
| natureza_from | string, opcional | RECLASSIFICATION only: the prior natureza |
| natureza_to | string, opcional | RECLASSIFICATION only: the corrected natureza |
| professional_name | string | obrigatório |
| record_digest | string | obrigatóriosha256 over this record's fields — committed to the journal hash chain as the evidence_hash of entry journal_seq_no |
| seq | integer | obrigatório1-based, per subject; append-only |
| subject_hash | string | obrigatóriosha256 of the artifact exactly as attested — a canonical projection of the stored artifact, never of an API response |
| subject_id | string | obrigatórioPERIOD/PIECE: '{scope_id}:{YYYY-MM}'; FISCDOC: the doc_id; RECLASSIFICATION: the obligation_id |
| subject_kind | string | obrigatórioPERIOD | FISCDOC | PIECE | RECLASSIFICATION |
CreateAttestationRequest
One act on one subject. ⛔ Not a list: one act, one signature (Phase-0 P2).
| Campo | Tipo | Detalhe |
|---|---|---|
| act | "ESCRITURACAO_ASSINADA" | "COMPETENCIA_APROVADA" | "CARTA_RESPONSABILIDADE" | "REABERTURA_AUTORIZADA" | obrigatórioREABERTURA_AUTORIZADA (PERIOD only, while CLOSED): the accountant's decision to reopen — binds the close being reopened, and is what POST .../reopen's attestation_seq names. It never makes a period ATTESTED |
| attested_via | string | obrigatórioUPPER_SNAKE, e.g. CONSOLE_CONTADOR |
| crc_number | string | obrigatório |
| crc_uf | string | obrigatório |
| firm_cnpj | string | obrigatório14 characters, no punctuation; alphanumeric CNPJs accepted |
| firm_crc | string | obrigatório |
| professional_name | string | obrigatório |
| subject_hash | string | obrigatórioThe current_subject_hash of the artifact the professional reviewed. A mismatch with the artifact now is 409 SUBJECT_HASH_MISMATCH |
| subject_id | string | obrigatório |
| subject_kind | "PERIOD" | "FISCDOC" | "PIECE" | obrigatórioRECLASSIFICATION is attested beside its correction, on PATCH /v1/obligations/{id}/natureza |
HTTPValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| detail | array de ValidationError |
ValidationError
| Campo | Tipo | Detalhe |
|---|---|---|
| ctx | object | |
| input | não declarado | |
| loc | array de string ou integer | obrigatório |
| msg | string | obrigatório |
| type | string | obrigatório |