{"openapi":"3.1.0","info":{"title":"Nota4You API","version":"1.0.0","summary":"Issue NFS-e Nacional invoices with IBS and CBS.","description":"REST API for integrators. It covers every endpoint that accepts an API key.\n\n- Authentication: `Authorization: Bearer \u003capi key\u003e`. Each operation lists the scope it needs.\n- JSON field names use snake_case. Decimal values are strings (`\"1500.0\"`, `\"0.02\"`); rates are fractions from 0 to 1.\n- Dates and times are ISO 8601. Times are in Brasília time.\n- Lists are paginated (25 per page, `page` parameter) with `Link` and `Total-Count` headers, unless the operation says otherwise.\n- Emission is asynchronous: `createInvoice` answers `202` with the invoice in `queued` state. Follow it with `getInvoice` or a webhook.\n- Errors use `application/problem+json` (`Problem`). `code` is stable; `title` is for people.\n- Rate limits: `RateLimit-*` headers on every response; `429` with `Retry-After`.\n\nDocs in Brazilian Portuguese: /docs/api. Versioning policy: /docs/versionamento.\n","contact":{"name":"Nota4You","url":"https://staging.nota4you.com.br/docs/api"}},"servers":[{"url":"https://app-staging.nota4you.com.br/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"API key"},{"name":"Taxpayers"},{"name":"Certificate"},{"name":"DPS series"},{"name":"Services"},{"name":"Customers"},{"name":"Privacy"},{"name":"Invoices"},{"name":"Statement import"},{"name":"Invoice reading"},{"name":"Municipal parameters"},{"name":"Webhooks"},{"name":"Reference data"}],"paths":{"/current_api_key":{"get":{"operationId":"getCurrentApiKey","tags":["API key"],"summary":"Read the calling API key","description":"Name, account, effective scopes, allowed taxpayers and expiry of the key in the request. Any scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The API key.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentApiKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers":{"get":{"operationId":"listTaxpayers","tags":["Taxpayers"],"summary":"List taxpayers","description":"Taxpayers of the account, by legal name. A key limited to some taxpayers sees only those. Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"name":"q","in":"query","description":"Words to find in the legal name, trade name or document. Accents and case are ignored.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Active"}],"responses":{"200":{"description":"One page of taxpayers.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Taxpayer"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createTaxpayer","tags":["Taxpayers"],"summary":"Create a taxpayer","description":"Creates a taxpayer with DPS series `00001`. Needs a key for all taxpayers. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taxpayer"],"additionalProperties":false,"properties":{"taxpayer":{"$ref":"#/components/schemas/TaxpayerCreateInput"}}}}}},"responses":{"201":{"description":"The new taxpayer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getTaxpayer","tags":["Taxpayers"],"summary":"Read a taxpayer","description":"The taxpayer with its first-invoice checklist (`setup`). Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The taxpayer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateTaxpayer","tags":["Taxpayers"],"summary":"Update a taxpayer","description":"Changes the given fields. The document cannot change. Send `active` false to deactivate. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["taxpayer"],"additionalProperties":false,"properties":{"taxpayer":{"$ref":"#/components/schemas/TaxpayerUpdateInput"}}}}}},"responses":{"200":{"description":"The taxpayer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxpayerDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/certificate":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"getCertificate","tags":["Certificate"],"summary":"Read the A1 certificate metadata","description":"Metadata of the taxpayer's A1 certificate. The file and its password never leave the server.\nUpload and removal need a session (owners and admins); for an assistant, use the MCP tool `request_certificate_upload`.\nScope `taxpayers:read`.\n","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The certificate.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Certificate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/dps_series":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"listDpsSeries","tags":["DPS series"],"summary":"List DPS series","description":"Every série of the taxpayer, by série. Not paginated. Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The séries.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DpsSeries"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createDpsSeries","tags":["DPS series"],"summary":"Create a DPS series","description":"A série cannot change after creation. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dps_series"],"additionalProperties":false,"properties":{"dps_series":{"type":"object","additionalProperties":false,"required":["series"],"properties":{"series":{"type":"string","maxLength":5,"examples":["00002"]},"next_number":{"$ref":"#/components/schemas/IntegerInput"}}}}}}}},"responses":{"201":{"description":"The new série.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DpsSeries"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/dps_series/{id}":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"},{"$ref":"#/components/parameters/Id"}],"patch":{"operationId":"updateDpsSeries","tags":["DPS series"],"summary":"Change the next DPS number","description":"Only `next_number` can change. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dps_series"],"additionalProperties":false,"properties":{"dps_series":{"type":"object","additionalProperties":false,"required":["next_number"],"properties":{"next_number":{"$ref":"#/components/schemas/IntegerInput"}}}}}}}},"responses":{"200":{"description":"The série.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DpsSeries"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/services":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"listServices","tags":["Services"],"summary":"List services","description":"The taxpayer's service catalog. Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"name":"q","in":"query","description":"Words to find in the name or codes.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Active"}],"responses":{"200":{"description":"One page of services.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createService","tags":["Services"],"summary":"Create a service","description":"Send the official codes: `national_service_code` (cTribNac, 6 digits), `nbs_code` (9 digits, dots allowed),\n`operation_indicator` (cIndOp) and `tax_classification_code` (cClassTrib). Find them in the reference data.\nAn immune service needs `iss_immunity_type`. Scope `taxpayers:write`.\n","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/ServiceInput"}}}}}},"responses":{"201":{"description":"The new service.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/services/{id}":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"},{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getService","tags":["Services"],"summary":"Read a service","description":"Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The service.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateService","tags":["Services"],"summary":"Update a service","description":"Changes the given fields. Send `active` false to deactivate. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["service"],"additionalProperties":false,"properties":{"service":{"$ref":"#/components/schemas/ServiceInput"}}}}}},"responses":{"200":{"description":"The service.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/customers":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"listCustomers","tags":["Customers"],"summary":"List customers","description":"Tomadores, intermediários and destinatários of the taxpayer. Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"name":"q","in":"query","description":"Words to find in the name or document.","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of customers.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createCustomer","tags":["Customers"],"summary":"Create a customer","description":"The address is optional; `country_code` defaults to `BR`. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"additionalProperties":false,"properties":{"customer":{"$ref":"#/components/schemas/CustomerInput"}}}}}},"responses":{"201":{"description":"The new customer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/customers/{id}":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"},{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getCustomer","tags":["Customers"],"summary":"Read a customer","description":"Scope `taxpayers:read`.","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The customer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateCustomer","tags":["Customers"],"summary":"Update a customer","description":"Changes the given fields. Scope `taxpayers:write`.","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"additionalProperties":false,"properties":{"customer":{"$ref":"#/components/schemas/CustomerInput"}}}}}},"responses":{"200":{"description":"The customer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/customers/{customer_id}/personal_data":{"parameters":[{"$ref":"#/components/parameters/CustomerId"}],"get":{"operationId":"getCustomerPersonalData","tags":["Privacy"],"summary":"Export a customer's personal data","description":"Every personal field held on the customer, the invoices that name it as customer, intermediary or recipient,\nand where the data was shared. Answers a data subject access request (LGPD art. 18). Scope `privacy:manage`.\nAnonymization is only available in the app.\n","security":[{"bearerAuth":["privacy:manage"]}],"responses":{"200":{"description":"The customer's personal data.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonalData"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/municipal_parameters":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"getMunicipalParameters","tags":["Municipal parameters"],"summary":"Read municipal parameters","description":"Whether a municipality joined the national environment, and its ISS rate for a service on a date,\nread from the ADN with the taxpayer's certificate (or the platform certificate). Scope `taxpayers:read`.\n","security":[{"bearerAuth":["taxpayers:read"]}],"parameters":[{"name":"municipality","in":"query","description":"IBGE code (7 digits). Default the taxpayer's municipality.","schema":{"type":"string"}},{"name":"service_code","in":"query","description":"cTribNac with 6 digits or with the 3-digit municipal code (9 digits). Without it, `iss_rate` is null.","schema":{"type":"string"}},{"name":"date","in":"query","description":"ISO 8601 date. Default today.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The parameters.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MunicipalParameters"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"}}}},"/taxpayers/{taxpayer_id}/invoice_previews":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"post":{"operationId":"previewInvoice","tags":["Invoices"],"summary":"Preview an invoice","description":"Validates the invoice and estimates its taxes. Saves nothing and sends nothing to Sefin Nacional. Scope `invoices:write`.","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoice"],"additionalProperties":false,"properties":{"invoice":{"$ref":"#/components/schemas/InvoiceInput"}}}}}},"responses":{"200":{"description":"The estimate.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePreview"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/invoices":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"listInvoices","tags":["Invoices"],"summary":"List invoices","description":"The taxpayer's invoices, newest first. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/InvoiceStatus"}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"invoice_import_id","in":"query","description":"Only the invoices issued from this statement import.","schema":{"type":"string","format":"uuid"}},{"name":"competence_from","in":"query","description":"ISO 8601 date, inclusive.","schema":{"type":"string","format":"date"}},{"name":"competence_to","in":"query","description":"ISO 8601 date, inclusive.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"One page of invoices.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createInvoice","tags":["Invoices"],"summary":"Emit an invoice","description":"Queues the invoice and answers `202` with it in `queued` state; the DPS goes to Sefin Nacional in the background.\nA repeated `Idempotency-Key` with the same body returns the first invoice; with another body, `409 idempotency_key_reused`.\nScope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invoice"],"additionalProperties":false,"properties":{"invoice":{"$ref":"#/components/schemas/InvoiceInput"}}}}}},"responses":{"202":{"description":"The queued invoice.","headers":{"Location":{"description":"Path of the invoice.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/invoice_imports":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"listInvoiceImports","tags":["Statement import"],"summary":"List statement imports","description":"The taxpayer's statement imports, newest first, without rows. Behind the `ai_invoice_wizard` feature flag. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"parameters":[{"$ref":"#/components/parameters/Page"}],"responses":{"200":{"description":"One page of imports.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceImport"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createInvoiceImport","tags":["Statement import"],"summary":"Import a commission statement","description":"Reads a text PDF statement (at most 10 MB and 60 pages) with a stored layout, checks that the rows add up to the printed total\nand that the statement belongs to the taxpayer, and keeps one row per future invoice. The file itself is not stored.\n`201` with the new import, also when it goes to `needs_review` or `learning`; `200` with the earlier import of the same file.\nWith no stored layout that reads the file, the import goes to `learning`: the format is learned in the background (about a minute),\nthen the import becomes `parsed` or `needs_review`. Follow it with `GET /invoice_imports/{id}`.\nNeeds the taxpayer's statement import settings. Behind the `ai_invoice_wizard` feature flag. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["invoice_import[file]"],"properties":{"invoice_import[file]":{"type":"string","format":"binary","description":"The statement PDF."}}}}}},"responses":{"200":{"description":"The earlier import of the same file.","headers":{"Location":{"description":"Path of the import.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportDetail"}}}},"201":{"description":"The new import.","headers":{"Location":{"description":"Path of the import.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/statement_import_settings":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"getStatementImportSettings","tags":["Statement import"],"summary":"Read the statement import settings","description":"The service, description template and SUSEP code used for statement imports. With nothing saved (`saved: false`), a suggestion:\nthe taxpayer's active brokerage service (cTribNac 10.01.02), if any, and the insurance description template.\nBehind the `ai_invoice_wizard` feature flag. Scope `taxpayers:read`.\n","security":[{"bearerAuth":["taxpayers:read"]}],"responses":{"200":{"description":"The settings.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementImportSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateStatementImportSettings","tags":["Statement import"],"summary":"Save the statement import settings","description":"Placeholders in `description_template`: `{reference}`, `{sub_reference}`, `{counterpart_name}`, `{counterpart_document}`,\n`{category}`, `{row_label}`, `{base_amount}`, `{rate}`, `{amount}`, `{date}`, `{issuer_name}`, `{payment_date}` and\n`{extras.\u003cname\u003e}`. A clause (text between commas or periods) whose placeholders are all empty for a row is left out.\nAn NFS-e can be read by anyone with its access key, and the default template holds `{counterpart_name}`.\n`preset` (`insurance`) in place of `service_id` uses the taxpayer's brokerage service (cTribNac 10.01.02), or creates it,\nand the preset template when none is saved. Behind the `ai_invoice_wizard` feature flag. Scope `taxpayers:write`.\n","security":[{"bearerAuth":["taxpayers:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["statement_import_settings"],"additionalProperties":false,"properties":{"statement_import_settings":{"$ref":"#/components/schemas/StatementImportSettingsInput"}}}}}},"responses":{"200":{"description":"The saved settings.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatementImportSettings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoice_imports/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getInvoiceImport","tags":["Statement import"],"summary":"Read a statement import","description":"The import with its rows, the rendered descriptions and the estimated taxes of the pending rows. `setup_errors` lists the\nproblems that block every row (for example a missing ISS rate). Behind the `ai_invoice_wizard` feature flag. Scope `invoices:read`.\n","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The import.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoice_imports/{invoice_import_id}/emission":{"parameters":[{"name":"invoice_import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"emitInvoiceImport","tags":["Statement import"],"summary":"Emit the invoices of a statement import","description":"Emits one invoice per listed row in the background; the other pending rows are skipped. Rows must be `pending`.\n`409 import_not_parsed` when the import is in review or was confirmed before; `409 provider_code_unconfirmed` while the\nstatement's SUSEP code waits for confirmation (see the provider confirmation). `422 customer_not_added` or\n`422 service_not_added` when the import proposes a customer or a service and the request does not add it. The import becomes `completed` when every\ninvoice has a final answer from Sefin Nacional, and the `invoice_import.completed` webhook goes out.\nBehind the `ai_invoice_wizard` feature flag. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emission"],"additionalProperties":false,"properties":{"emission":{"type":"object","required":["row_ids"],"additionalProperties":false,"properties":{"row_ids":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Uuid"}},"add_customer":{"type":"boolean","default":false,"description":"Adds the proposed customer (`proposed_customer`) before the rows emit."},"add_service":{"type":"boolean","default":false,"description":"Adds the proposed service of the settings area (`proposed_service`) before the rows emit."}}}}}}}},"responses":{"202":{"description":"The import in `emitting` state.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoice_imports/{invoice_import_id}/provider_confirmation":{"parameters":[{"name":"invoice_import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"confirmInvoiceImportProvider","tags":["Statement import"],"summary":"Confirm the broker SUSEP code of a statement","description":"For a statement without the broker's CNPJ, read before any SUSEP code was saved (`provider_code_unconfirmed: true`).\n`accepted: true` saves `provider_code` as the settings' SUSEP code; later statements must match it.\n`accepted: false` sends the import to review with `provider_mismatch` and drops its rows.\n`409 import_not_parsed`, or `409 provider_code_confirmed` when nothing waits for confirmation.\nBehind the `ai_invoice_wizard` feature flag. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider_confirmation"],"additionalProperties":false,"properties":{"provider_confirmation":{"type":"object","required":["accepted"],"additionalProperties":false,"properties":{"accepted":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"The import after the answer.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceImportDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoice_readings":{"post":{"operationId":"createInvoiceReading","tags":["Invoice reading"],"summary":"Read an issued invoice","description":"Reads one NFS-e the taxpayer issued before, to propose the emitter, the customer, the service and the next invoice.\nThe file is not stored, and the reading expires after one day.\n- A national NFS-e XML is read at once: `201` with `status: read`.\n- A PDF (municipal NFS-e or DANFSe, at most 10 MB) is read in the background by an AI model: `202` with `status: reading`.\n  Follow it with `GET /invoice_readings/{id}`. CPF numbers are masked before the text leaves the server.\n- The same file within one day: `200` with the earlier reading.\nError codes (`422`): `file_too_large`, `file_not_supported`, `file_not_pdf`, `file_encrypted`, `file_too_many_pages`,\n`file_without_text`, `file_not_invoice` (a PDF that is not an invoice, for example a statement),\n`invoice_reading_unavailable` (PDF reading is off) and `invoice_reading_limit` (the monthly PDF limit of the account).\nWithout `taxpayer_id`, the key needs access to all taxpayers. Behind the `ai_invoice_wizard` feature flag. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["invoice_reading[file]"],"properties":{"invoice_reading[file]":{"type":"string","format":"binary","description":"The invoice XML or PDF."},"invoice_reading[taxpayer_id]":{"type":"string","format":"uuid","description":"The taxpayer the invoice is for","when known.":null}}}}}},"responses":{"200":{"description":"The earlier reading of the same file.","headers":{"Location":{"description":"Path of the reading.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceReading"}}}},"201":{"description":"The XML, read.","headers":{"Location":{"description":"Path of the reading.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceReading"}}}},"202":{"description":"The PDF, being read.","headers":{"Location":{"description":"Path of the reading.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceReading"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoice_readings/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getInvoiceReading","tags":["Invoice reading"],"summary":"Read an invoice reading","description":"The values read and, for each record, the match among the existing ones (`null` when there is none yet). Matches are\ncomputed on each request. Only the user who sent the file sees the reading. After one day, `404`.\nBehind the `ai_invoice_wizard` feature flag. Scope `invoices:read`.\n","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The reading.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceReading"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/taxpayers/{taxpayer_id}/invoice_stats":{"parameters":[{"$ref":"#/components/parameters/TaxpayerId"}],"get":{"operationId":"getInvoiceStats","tags":["Invoices"],"summary":"Read 12-month invoice totals","description":"The last 12 months, oldest first. `authorized_count` and `authorized_value` by the Brasília month of `authorized_at`,\n`rejected_count` by the month of `issued_at`. Empty months are zero. Scope `invoices:read`.\n","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The totals.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceStats"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getInvoice","tags":["Invoices"],"summary":"Read an invoice","description":"The invoice with its taxes, status and messages. At most 60 reads a minute per API key. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The invoice.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"correctInvoice","tags":["Invoices"],"summary":"Correct a rejected invoice","description":"Changes the given fields of a rejected invoice and sends it again with the same DPS number.\nThe série cannot change. `409 invoice_not_rejected` for an invoice in another state.\nFor a substitute, `409 substituted_invoice_not_authorized` once the original is no longer open to substitution. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"invoice":{"$ref":"#/components/schemas/InvoiceCorrectionInput"}}}}}},"responses":{"202":{"description":"The queued invoice.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/retransmission":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"post":{"operationId":"retransmitInvoice","tags":["Invoices"],"summary":"Send a rejected invoice again","description":"Sends the rejected invoice again, unchanged. `409 invoice_not_rejected` for an invoice in another state.\nFor a substitute, `409 substituted_invoice_not_authorized` once the original is no longer open to substitution. Scope `invoices:write`.\n","security":[{"bearerAuth":["invoices:write"]}],"responses":{"202":{"description":"The queued invoice.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/xml":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"getInvoiceXml","tags":["Invoices"],"summary":"Download the NFS-e XML","description":"The authorized NFS-e XML. `404` until authorization. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The XML file.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/dps_xml":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"getInvoiceDpsXml","tags":["Invoices"],"summary":"Download the signed DPS XML","description":"The DPS XML as sent to Sefin Nacional. `404` until the job builds it. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The XML file.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/danfse":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"getInvoiceDanfse","tags":["Invoices"],"summary":"Download the DANFSe PDF","description":"The DANFSe of an authorized invoice. `404` until authorization. At most 30 a minute per API key. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The PDF file.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/cancellation":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"post":{"operationId":"cancelInvoice","tags":["Invoices"],"summary":"Cancel an authorized invoice","description":"Queues the cancellation event (101101) and answers `202` with it in `queued` state. Sefin Nacional registers it\nin the background: the invoice changes to `cancelled`, or the event to `rejected` with the Sefin messages.\nFollow it with `listInvoiceEvents`, `getInvoice` or a webhook. Irreversible.\n`409 invoice_not_authorized` for an invoice in another state; `409 invoice_event_pending` while a cancellation\nis queued or registered. A rejected cancellation can be sent again. Scope `invoices:cancel`.\n","security":[{"bearerAuth":["invoices:cancel"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cancellation"],"additionalProperties":false,"properties":{"cancellation":{"$ref":"#/components/schemas/CancellationInput"}}}}}},"responses":{"202":{"description":"The queued cancellation event.","headers":{"Location":{"description":"Path of the invoice's event list.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceEvent"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/substitution":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"post":{"operationId":"createInvoiceSubstitution","tags":["Invoices"],"summary":"Substitute an authorized invoice","description":"Queues a new invoice that replaces this one and answers `202` with it in `queued` state. The fields left out of\n`invoice` copy the original; the série can change. Its DPS carries the original's access key (`subst`).\nWhen Sefin Nacional authorizes the substitute, it registers the cancellation by substitution (105102) on the\noriginal: the original changes to `substituted` and the event shows in `listInvoiceEvents`.\nIf Sefin Nacional rejects the substitute, the original stays `authorized`; correct or retransmit the substitute.\nA repeated `Idempotency-Key` with the same body returns the first substitute; with another body, `409 idempotency_key_reused`.\n`409 invoice_not_authorized` for an invoice in another state; `409 invoice_event_pending` while a cancellation\nor another substitute is in progress. Scopes `invoices:write` and `invoices:cancel`.\n","security":[{"bearerAuth":["invoices:write","invoices:cancel"]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["substitution"],"additionalProperties":false,"properties":{"invoice":{"$ref":"#/components/schemas/InvoiceInput"},"substitution":{"$ref":"#/components/schemas/SubstitutionInput"}}}}}},"responses":{"202":{"description":"The queued substitute.","headers":{"Location":{"description":"Path of the substitute.","required":true,"schema":{"type":"string"}},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/events":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"listInvoiceEvents","tags":["Invoices"],"summary":"List the events of an invoice","description":"Cancellation and substitution events, oldest first, rejected ones included. Not paginated. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The events.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceEvent"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/invoices/{invoice_id}/events/{event_id}/xml":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"},{"$ref":"#/components/parameters/EventId"}],"get":{"operationId":"getInvoiceEventXml","tags":["Invoices"],"summary":"Download the event XML","description":"The event XML that Sefin Nacional registered. `404` until registration. Scope `invoices:read`.","security":[{"bearerAuth":["invoices:read"]}],"responses":{"200":{"description":"The XML file.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_endpoints":{"get":{"operationId":"listWebhookEndpoints","tags":["Webhooks"],"summary":"List webhook endpoints","description":"The account's endpoints, oldest first. Not paginated (at most 10). Needs a key for all taxpayers. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"200":{"description":"The endpoints.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"The response has `secret`, shown only here and after a rotation. Needs a key for all taxpayers. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhook_endpoint"],"additionalProperties":false,"properties":{"webhook_endpoint":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}}},"responses":{"201":{"description":"The new endpoint with its secret.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_endpoints/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getWebhookEndpoint","tags":["Webhooks"],"summary":"Read a webhook endpoint","description":"The endpoint without its secret. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"200":{"description":"The endpoint.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateWebhookEndpoint","tags":["Webhooks"],"summary":"Update a webhook endpoint","description":"Changes `url`, `description`, `event_types` or `active`. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhook_endpoint"],"additionalProperties":false,"properties":{"webhook_endpoint":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}}}},"responses":{"200":{"description":"The endpoint.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteWebhookEndpoint","tags":["Webhooks"],"summary":"Delete a webhook endpoint","description":"Deletes the endpoint and its deliveries. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"204":{"description":"Deleted.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_endpoints/{webhook_endpoint_id}/secret_rotation":{"parameters":[{"$ref":"#/components/parameters/WebhookEndpointId"}],"post":{"operationId":"rotateWebhookEndpointSecret","tags":["Webhooks"],"summary":"Replace the signing secret","description":"The old secret stops working at once. The response has the new `secret`, shown only here. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"200":{"description":"The endpoint with its new secret.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_endpoints/{webhook_endpoint_id}/test_delivery":{"parameters":[{"$ref":"#/components/parameters/WebhookEndpointId"}],"post":{"operationId":"sendWebhookTest","tags":["Webhooks"],"summary":"Send a test event","description":"Sends a `webhook.test` event. `409 webhook_endpoint_inactive` for an inactive endpoint. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"202":{"description":"The queued delivery.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_deliveries":{"get":{"operationId":"listWebhookDeliveries","tags":["Webhooks"],"summary":"List webhook deliveries","description":"Deliveries, newest first, without payload. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"name":"webhook_endpoint_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/WebhookDeliveryStatus"}},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"invoice_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"One page of deliveries.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_deliveries/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"operationId":"getWebhookDelivery","tags":["Webhooks"],"summary":"Read a webhook delivery","description":"The delivery with its payload. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"200":{"description":"The delivery.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/webhook_deliveries/{webhook_delivery_id}/redelivery":{"parameters":[{"name":"webhook_delivery_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"redeliverWebhook","tags":["Webhooks"],"summary":"Send a delivery again","description":"Sends a delivered or failed delivery again, once. `409 delivery_pending` while it is pending. Scope `webhooks:manage`.","security":[{"bearerAuth":["webhooks:manage"]}],"responses":{"202":{"description":"The queued delivery.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/countries":{"get":{"operationId":"listCountries","tags":["Reference data"],"summary":"List countries","description":"Every country, by name. Not paginated. Any scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The countries.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/currencies":{"get":{"operationId":"listCurrencies","tags":["Reference data"],"summary":"List currencies","description":"The ISO 4217 currencies in use (no funds or metals), by ISO code. Not paginated. Any scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The currencies.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Currency"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/states":{"get":{"operationId":"listStates","tags":["Reference data"],"summary":"List states","description":"Every Brazilian state, by name. Not paginated. Any scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The states.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/State"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/municipalities":{"get":{"operationId":"listMunicipalities","tags":["Reference data"],"summary":"Search municipalities","description":"Any scope.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Query"},{"name":"uf","in":"query","schema":{"type":"string","examples":["SP"]}},{"name":"ibge_code","in":"query","schema":{"type":"string","examples":["3550308"]}}],"responses":{"200":{"description":"One page of municipalities.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MunicipalityRow"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/national_service_codes":{"get":{"operationId":"listNationalServiceCodes","tags":["Reference data"],"summary":"Search national service codes (cTribNac)","description":"Search by code, LC 116 item or description. Any scope.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Query"}],"responses":{"200":{"description":"One page of codes.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NationalServiceCode"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/nbs_codes":{"get":{"operationId":"listNbsCodes","tags":["Reference data"],"summary":"Search NBS codes","description":"9-digit NBS codes. `national_service_code` keeps the correlated codes. Any scope.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Query"},{"name":"national_service_code","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of codes.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NbsCode"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/operation_indicators":{"get":{"operationId":"listOperationIndicators","tags":["Reference data"],"summary":"Search operation indicators (cIndOp)","description":"Any scope.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Query"},{"name":"national_service_code","in":"query","schema":{"type":"string"}},{"name":"nbs_code","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of indicators.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OperationIndicator"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/tax_classifications":{"get":{"operationId":"listTaxClassifications","tags":["Reference data"],"summary":"Search tax classifications (cClassTrib)","description":"Classifications valid on `date`. Any scope.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Query"},{"name":"cst","in":"query","schema":{"type":"string"}},{"name":"national_service_code","in":"query","schema":{"type":"string"}},{"name":"nbs_code","in":"query","schema":{"type":"string"}},{"name":"operation_indicator","in":"query","schema":{"type":"string"}},{"name":"date","in":"query","description":"ISO 8601 date. Default today.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"One page of classifications.","headers":{"Link":{"$ref":"#/components/headers/Link"},"Total-Count":{"$ref":"#/components/headers/Total-Count"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaxClassification"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/reference/postal_codes/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"CEP with 8 digits. Punctuation is allowed.","schema":{"type":"string","examples":["01310-100"]}}],"get":{"operationId":"getPostalCode","tags":["Reference data"],"summary":"Look up a CEP","description":"Street, district and municipality of a CEP. At most 30 a minute per API key. Any scope.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The address.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostalCode"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/reference/companies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"CNPJ with 14 characters. Punctuation is allowed.","schema":{"type":"string","examples":["11222333000181"]}}],"get":{"operationId":"getCompany","tags":["Reference data"],"summary":"Look up a CNPJ","description":"Registry data of a CNPJ. `422 invalid_cnpj` for wrong check digits; `404` outside the registry.\nAt most 20 a minute per API key. Any scope.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The company.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableContent"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"webhooks":{"invoice.authorized":{"post":{"operationId":"invoiceAuthorizedWebhook","tags":["Webhooks"],"summary":"Invoice authorized","description":"Sefin Nacional authorized the NFS-e.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoicePayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"invoice.rejected":{"post":{"operationId":"invoiceRejectedWebhook","tags":["Webhooks"],"summary":"Invoice rejected","description":"Sefin Nacional rejected the DPS, or the app refused it before transmission.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoicePayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"invoice.cancelled":{"post":{"operationId":"invoiceCancelledWebhook","tags":["Webhooks"],"summary":"Invoice cancelled","description":"The cancellation event was registered.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoicePayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"invoice.substituted":{"post":{"operationId":"invoiceSubstitutedWebhook","tags":["Webhooks"],"summary":"Invoice substituted","description":"A substitute invoice was authorized. The payload is the original invoice.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoicePayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"invoice_event.rejected":{"post":{"operationId":"invoiceEventRejectedWebhook","tags":["Webhooks"],"summary":"Invoice event rejected","description":"Sefin Nacional rejected a cancellation event.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceEventPayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"certificate.expiring":{"post":{"operationId":"certificateExpiringWebhook","tags":["Webhooks"],"summary":"Certificate expiring","description":"A taxpayer certificate expires in 30, 15, 7, 1 or 0 days. One event per certificate and day.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCertificatePayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"invoice_import.completed":{"post":{"operationId":"invoiceImportCompletedWebhook","tags":["Webhooks"],"summary":"Statement import completed","description":"Every invoice of a statement import has a final answer from Sefin Nacional, or failed. Carries no personal data.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInvoiceImportPayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}},"webhook.test":{"post":{"operationId":"webhookTestWebhook","tags":["Webhooks"],"summary":"Test delivery","description":"Sent by POST /webhook_endpoints/{webhook_endpoint_id}/test_delivery to that endpoint only.","parameters":[{"$ref":"#/components/parameters/WebhookEventIdHeader"},{"$ref":"#/components/parameters/WebhookEventTypeHeader"},{"$ref":"#/components/parameters/WebhookDeliveryAttemptHeader"},{"$ref":"#/components/parameters/WebhookSignatureHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestPayload"}}}},"responses":{"2XX":{"description":"Received. Any other status, a redirect or a timeout schedules a new attempt."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the app (Configurações \u003e Chaves de API), sent as `Authorization: Bearer \u003ckey\u003e`.\nScopes: `taxpayers:read`, `taxpayers:write`, `invoices:read`, `invoices:write`, `webhooks:manage`.\nA key limited to some taxpayers sees only those.\n"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"TaxpayerId":{"name":"taxpayer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"CustomerId":{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"InvoiceId":{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"EventId":{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"WebhookEndpointId":{"name":"webhook_endpoint_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","description":"Page number, from 1. 25 items a page.","schema":{"type":"integer","minimum":1}},"Query":{"name":"q","in":"query","description":"Words to find in the code and the description, in any order. Accents and case are ignored.","schema":{"type":"string"}},"Active":{"name":"active","in":"query","description":"`true` or `false`.","schema":{"type":"boolean"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"1 to 255 characters, unique per invoice (a UUID works). A retry with the same key and body returns the first invoice.","schema":{"type":"string","minLength":1,"maxLength":255}},"WebhookEventIdHeader":{"name":"X-Nota4you-Event-Id","in":"header","required":true,"description":"The event id. The same for every delivery and attempt of one event. Deduplicate on it.","schema":{"$ref":"#/components/schemas/Uuid"}},"WebhookEventTypeHeader":{"name":"X-Nota4you-Event-Type","in":"header","required":true,"schema":{"type":"string","examples":["invoice.authorized"]}},"WebhookDeliveryAttemptHeader":{"name":"X-Nota4you-Delivery-Attempt","in":"header","required":true,"schema":{"type":"string","examples":["1"]}},"WebhookSignatureHeader":{"name":"X-Nota4you-Signature","in":"header","required":true,"description":"`t=\u003cunix time\u003e,v1=\u003chex HMAC-SHA256 of \"t.body\" with the endpoint secret\u003e`.","schema":{"type":"string"}}},"headers":{"Link":{"description":"RFC 8288 links to the first, previous, next and last pages.","schema":{"type":"string"}},"Total-Count":{"description":"Number of items in every page.","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"}},"RateLimit-Limit":{"description":"Requests allowed in the window of the closest limit.","schema":{"type":"string","pattern":"^[0-9]+$"}},"RateLimit-Remaining":{"description":"Requests left in the window.","schema":{"type":"string","pattern":"^[0-9]+$"}},"RateLimit-Reset":{"description":"Seconds until the window resets.","schema":{"type":"string","pattern":"^[0-9]+$"}},"RateLimit-Policy":{"description":"The limit and its window in seconds, for example `300;w=300`.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before the next request.","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"}}},"responses":{"BadRequest":{"description":"The request is malformed: a missing root key, an invalid date or code (`bad_request`),\nor no `Idempotency-Key` (`idempotency_key_required`).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"No valid API key: `unauthenticated` (no credentials), `invalid_api_key` (unknown or revoked) or `api_key_expired`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"The key cannot do this: `insufficient_scope`, `forbidden` (the member's role), `all_taxpayers_required`\n(the operation needs a key for all taxpayers) or `session_required`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource does not exist or the key cannot see it (`not_found`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"The resource is in the wrong state: `idempotency_key_reused`, `invoice_not_rejected`, `invoice_not_authorized`,\n`invoice_event_pending`, `webhook_endpoint_inactive` or `delivery_pending`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"UnprocessableContent":{"description":"`validation_failed` with one entry in `errors` for each invalid field, or a specific code such as\n`certificate_missing` or `invalid_cnpj`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"A rate limit was reached (`rate_limited`). Wait `Retry-After` seconds.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"BadGateway":{"description":"The NFS-e Nacional services did not answer (`nfse_nacional_unavailable`). Try again later.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ServiceUnavailable":{"description":"The lookup service did not answer (`postal_code_lookup_unavailable`, `company_lookup_unavailable`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"An RFC 9457 problem. Read `code`, not `title`.","additionalProperties":false,"required":["title","status","code","errors"],"properties":{"title":{"type":"string","description":"Short text in Brazilian Portuguese."},"status":{"type":"integer"},"code":{"type":"string","examples":["validation_failed"]},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ProblemError"}}}},"ProblemError":{"type":"object","additionalProperties":false,"required":["field","code","message"],"properties":{"field":{"type":"string","description":"The field in lowerCamelCase","for example `serviceValue` or `address`.":null},"code":{"type":"string","examples":["blank","invalid","greater_than"]},"message":{"type":"string","description":"Text in Brazilian Portuguese."}}},"Decimal":{"type":"string","pattern":"^-?[0-9]+(\\.[0-9]+)?$","examples":["1500.0"]},"NullableDecimal":{"type":["string","null"],"pattern":"^-?[0-9]+(\\.[0-9]+)?$"},"DecimalInput":{"description":"A number or a decimal string. Rates are fractions from 0 to 1.","type":["string","number","null"]},"IntegerInput":{"type":["integer","string"]},"BooleanInput":{"type":["boolean","string"]},"Uuid":{"type":"string","format":"uuid"},"DateTime":{"type":"string","format":"date-time"},"NullableDateTime":{"type":["string","null"],"format":"date-time"},"MunicipalityRef":{"type":"object","additionalProperties":false,"required":["ibge_code","name","uf"],"properties":{"ibge_code":{"type":"string","examples":["3550308"]},"name":{"type":"string"},"uf":{"type":"string","examples":["SP"]}}},"NullableMunicipalityRef":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/MunicipalityRef"}]},"TaxpayerRef":{"type":"object","additionalProperties":false,"required":["id","legal_name","document"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"legal_name":{"type":"string"},"document":{"type":"string"}}},"Account":{"type":"object","additionalProperties":false,"required":["id","name","slug"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"CurrentApiKey":{"type":"object","additionalProperties":false,"required":["id","name","prefix","all_taxpayers","expires_at","scopes","taxpayers","account"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"all_taxpayers":{"type":"boolean"},"expires_at":{"$ref":"#/components/schemas/NullableDateTime"},"scopes":{"type":"array","description":"The scopes the key can use now (the key's scopes that the member's role allows).","items":{"type":"string"}},"taxpayers":{"type":"array","description":"The allowed taxpayers of a limited key; empty for a key for all taxpayers.","items":{"$ref":"#/components/schemas/TaxpayerRef"}},"account":{"$ref":"#/components/schemas/Account"}}},"Address":{"type":"object","additionalProperties":false,"required":["postal_code","street","number","complement","district","country_code","foreign_city","foreign_region","municipality"],"properties":{"postal_code":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":["string","null"]},"district":{"type":"string"},"country_code":{"type":"string","examples":["BR"]},"foreign_city":{"type":["string","null"]},"foreign_region":{"type":["string","null"]},"municipality":{"$ref":"#/components/schemas/NullableMunicipalityRef"}}},"BrazilianAddressInput":{"type":"object","additionalProperties":false,"properties":{"postal_code":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":["string","null"]},"district":{"type":"string"},"municipality_ibge_code":{"type":"string"}}},"AddressInput":{"type":"object","additionalProperties":false,"properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2. Default `BR`."},"postal_code":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":["string","null"]},"district":{"type":"string"},"municipality_ibge_code":{"type":["string","null"],"description":"Brazilian addresses."},"foreign_city":{"type":["string","null"],"description":"Foreign addresses."},"foreign_region":{"type":["string","null"],"description":"Foreign addresses."}}},"SimplesStatus":{"type":"string","enum":["not_opted","mei","me_epp","pending"]},"SimplesRegime":{"type":["string","null"],"enum":["all_by_simples","federal_by_simples","none_by_simples",null]},"SimplesIbscbsRegime":{"type":["string","null"],"enum":["both_by_simples","cbs_by_simples","both_regular",null]},"SpecialRegime":{"type":"string","enum":["none","cooperative","estimate","municipal_micro_enterprise","notary","self_employed","professional_partnership","other"]},"FederalTaxRegime":{"type":["string","null"],"enum":["presumido","real",null],"description":"Lucro Presumido or Lucro Real. Set only for a CNPJ outside the Simples Nacional: `not_opted`, or ME/EPP with `none_by_simples`; default `presumido` there, null elsewhere. Gives the own PIS/COFINS rates (0.65%/3% or 1.65%/7.6%)."},"TaxpayerCertificateSummary":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["not_after","expired","expiring"],"properties":{"not_after":{"$ref":"#/components/schemas/DateTime"},"expired":{"type":"boolean"},"expiring":{"type":"boolean","description":"Ends within 30 days."}}}]},"Taxpayer":{"allOf":[{"$ref":"#/components/schemas/TaxpayerFields"}],"unevaluatedProperties":false},"TaxpayerFields":{"type":"object","required":["id","document_type","document","legal_name","trade_name","municipal_registration","email","phone","simples_status","simples_regime","simples_ibscbs_regime","special_regime","federal_tax_regime","approximate_federal_rate","approximate_state_rate","approximate_municipal_rate","simples_total_rate","simples_iss_rate","active","created_at","updated_at","address","shared","owner_account_name","warnings","certificate"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"document_type":{"type":"string","enum":["cnpj","cpf"]},"document":{"type":"string","description":"CNPJ (14 characters) or CPF (11 digits)","no punctuation.":null},"legal_name":{"type":"string"},"trade_name":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"email":{"type":"string"},"phone":{"type":["string","null"]},"simples_status":{"$ref":"#/components/schemas/SimplesStatus"},"simples_regime":{"$ref":"#/components/schemas/SimplesRegime"},"simples_ibscbs_regime":{"$ref":"#/components/schemas/SimplesIbscbsRegime"},"special_regime":{"$ref":"#/components/schemas/SpecialRegime"},"federal_tax_regime":{"$ref":"#/components/schemas/FederalTaxRegime"},"approximate_federal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_state_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_municipal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"simples_total_rate":{"$ref":"#/components/schemas/NullableDecimal"},"simples_iss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"active":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"address":{"$ref":"#/components/schemas/Address"},"shared":{"type":"boolean","description":"True when another account shares this taxpayer with your account. See accountant access."},"owner_account_name":{"type":["string","null"],"description":"The name of the account that holds the taxpayer","when `shared`.":null},"warnings":{"type":"array","description":"For example `municipality_not_active`.","items":{"type":"string"}},"certificate":{"$ref":"#/components/schemas/TaxpayerCertificateSummary"}}},"TaxpayerDetail":{"allOf":[{"$ref":"#/components/schemas/TaxpayerFields"}],"unevaluatedProperties":false,"required":["setup"],"properties":{"setup":{"type":"object","description":"First-invoice checklist.","additionalProperties":false,"required":["services_count","customers_count","authorized_invoices_count"],"properties":{"services_count":{"type":"integer","description":"Active services."},"customers_count":{"type":"integer"},"authorized_invoices_count":{"type":"integer"}}}}},"TaxpayerUpdateInput":{"type":"object","additionalProperties":false,"properties":{"legal_name":{"type":"string"},"trade_name":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"email":{"type":"string"},"phone":{"type":["string","null"]},"simples_status":{"$ref":"#/components/schemas/SimplesStatus"},"simples_regime":{"$ref":"#/components/schemas/SimplesRegime"},"simples_ibscbs_regime":{"$ref":"#/components/schemas/SimplesIbscbsRegime"},"special_regime":{"$ref":"#/components/schemas/SpecialRegime"},"federal_tax_regime":{"$ref":"#/components/schemas/FederalTaxRegime"},"active":{"$ref":"#/components/schemas/BooleanInput"},"approximate_federal_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_state_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_municipal_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_total_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_iss_rate":{"$ref":"#/components/schemas/DecimalInput","description":"ME/EPP with `simples_regime` `all_by_simples`: the ISS rate fraction of its Simples Nacional range, 0.018 to 0.05. The DPS declares it when the customer withholds the ISS."},"address":{"$ref":"#/components/schemas/BrazilianAddressInput"}}},"TaxpayerCreateInput":{"type":"object","additionalProperties":false,"properties":{"document_type":{"type":"string","enum":["cnpj","cpf"]},"document":{"type":"string"},"next_dps_number":{"$ref":"#/components/schemas/IntegerInput"},"legal_name":{"type":"string"},"trade_name":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"email":{"type":"string"},"phone":{"type":["string","null"]},"simples_status":{"$ref":"#/components/schemas/SimplesStatus"},"simples_regime":{"$ref":"#/components/schemas/SimplesRegime"},"simples_ibscbs_regime":{"$ref":"#/components/schemas/SimplesIbscbsRegime"},"special_regime":{"$ref":"#/components/schemas/SpecialRegime"},"federal_tax_regime":{"$ref":"#/components/schemas/FederalTaxRegime"},"active":{"$ref":"#/components/schemas/BooleanInput"},"approximate_federal_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_state_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_municipal_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_total_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_iss_rate":{"$ref":"#/components/schemas/DecimalInput","description":"ME/EPP with `simples_regime` `all_by_simples`: the ISS rate fraction of its Simples Nacional range, 0.018 to 0.05. The DPS declares it when the customer withholds the ISS."},"address":{"$ref":"#/components/schemas/BrazilianAddressInput"}}},"Certificate":{"type":"object","additionalProperties":false,"required":["id","subject_document","subject_name","issuer","serial","not_before","not_after","created_at","expired","expiring"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"subject_document":{"type":"string"},"subject_name":{"type":"string"},"issuer":{"type":"string"},"serial":{"type":"string"},"not_before":{"$ref":"#/components/schemas/DateTime"},"not_after":{"$ref":"#/components/schemas/DateTime"},"created_at":{"$ref":"#/components/schemas/DateTime"},"expired":{"type":"boolean"},"expiring":{"type":"boolean","description":"Ends within 30 days."}}},"DpsSeries":{"type":"object","additionalProperties":false,"required":["id","series","next_number","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"series":{"type":"string","examples":["00001"]},"next_number":{"type":"integer"},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"}}},"IssTaxation":{"type":"string","enum":["taxable","immune","export","non_incidence"]},"IssImmunityType":{"type":["string","null"],"enum":["reciprocal","religious","parties_unions_education_welfare","books_press","phonograms",null]},"IssWithholding":{"type":"string","enum":["not_withheld","by_customer","by_intermediary"]},"SupplyMode":{"type":["string","null"],"description":"comExt/mdPrestacao. Required for an export service.","enum":["cross_border","consumption_in_brazil","temporary_presence","consumption_abroad",null]},"ProviderTradeSupport":{"type":"string","description":"comExt/mecAFComexP, codes 01 to 08 in order.","enum":["none","acc","ace","bndes_exim_post_shipment","bndes_exim_pre_shipment","fge","proex_equalization","proex_financing"]},"CustomerTradeSupport":{"type":"string","description":"comExt/mecAFComexT, codes 01 to 26 in order.","enum":["none","public_administration","equipment_leasing","aircraft_leasing","export_agent_commission","cargo_abroad","fifa_subsidiary","fifa","freight_and_vessel_leasing","aeronautical_material","goods_promotion","tourism_promotion","brazil_promotion","services_promotion","recine","recopa","trademarks_patents","reicomp","reidi","repenec","repes","retaero","retid","royalties_technical_assistance","conformity_assessment","zpe"]},"RelatedParty":{"type":"string","description":"comExt/vincPrest, codes 0 to 6 in order.","enum":["none","controlled","controlling","affiliated","head_office","branch","other"]},"ForeignTrade":{"type":["object","null"],"additionalProperties":false,"description":"The comExt group. Set when the customer or intermediary address is abroad, the place of supply is abroad, or the service is an export.","required":["currency_code","foreign_service_value","supply_mode","related_party","provider_trade_support","customer_trade_support","share_with_mdic"],"properties":{"currency_code":{"type":"string","examples":["USD"],"description":"ISO 4217."},"foreign_service_value":{"$ref":"#/components/schemas/Decimal"},"supply_mode":{"type":"string","enum":["cross_border","consumption_in_brazil","temporary_presence","consumption_abroad"]},"related_party":{"$ref":"#/components/schemas/RelatedParty"},"provider_trade_support":{"$ref":"#/components/schemas/ProviderTradeSupport"},"customer_trade_support":{"$ref":"#/components/schemas/CustomerTradeSupport"},"share_with_mdic":{"type":"boolean"}}},"Service":{"type":"object","additionalProperties":false,"required":["id","name","description_template","municipal_tax_code","tax_classification_code","iss_taxation","iss_immunity_type","iss_rate","iss_withholding","zfm_alc","pis_cofins_cst","irrf_rate","csll_rate","inss_rate","supply_mode","provider_trade_support","customer_trade_support","share_with_mdic","active","created_at","updated_at","national_service_code","nbs_code","operation_indicator"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"description_template":{"type":"string"},"municipal_tax_code":{"type":["string","null"]},"tax_classification_code":{"type":"string"},"iss_taxation":{"$ref":"#/components/schemas/IssTaxation"},"iss_immunity_type":{"$ref":"#/components/schemas/IssImmunityType"},"iss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"iss_withholding":{"$ref":"#/components/schemas/IssWithholding"},"zfm_alc":{"type":"boolean"},"pis_cofins_cst":{"type":["string","null"]},"irrf_rate":{"$ref":"#/components/schemas/NullableDecimal"},"csll_rate":{"$ref":"#/components/schemas/NullableDecimal"},"inss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"supply_mode":{"$ref":"#/components/schemas/SupplyMode"},"provider_trade_support":{"$ref":"#/components/schemas/ProviderTradeSupport"},"customer_trade_support":{"$ref":"#/components/schemas/CustomerTradeSupport"},"share_with_mdic":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"national_service_code":{"type":"object","additionalProperties":false,"required":["code","description"],"properties":{"code":{"type":"string"},"description":{"type":"string"}}},"nbs_code":{"type":"object","additionalProperties":false,"required":["code","formatted_code","description"],"properties":{"code":{"type":"string"},"formatted_code":{"type":"string"},"description":{"type":"string"}}},"operation_indicator":{"type":"object","additionalProperties":false,"required":["code","description"],"properties":{"code":{"type":"string"},"description":{"type":"string"}}}}},"ServiceInput":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"description_template":{"type":"string"},"national_service_code":{"type":"string","examples":["010101"]},"municipal_tax_code":{"type":["string","null"]},"nbs_code":{"type":"string","examples":["1.1502.10.00"]},"operation_indicator":{"type":"string","examples":["100301"]},"tax_classification_code":{"type":"string","examples":["000001"]},"iss_taxation":{"$ref":"#/components/schemas/IssTaxation"},"iss_immunity_type":{"$ref":"#/components/schemas/IssImmunityType"},"iss_rate":{"$ref":"#/components/schemas/DecimalInput"},"iss_withholding":{"$ref":"#/components/schemas/IssWithholding"},"zfm_alc":{"$ref":"#/components/schemas/BooleanInput"},"pis_cofins_cst":{"type":["string","null"]},"irrf_rate":{"$ref":"#/components/schemas/DecimalInput"},"csll_rate":{"$ref":"#/components/schemas/DecimalInput"},"inss_rate":{"$ref":"#/components/schemas/DecimalInput"},"supply_mode":{"$ref":"#/components/schemas/SupplyMode"},"provider_trade_support":{"$ref":"#/components/schemas/ProviderTradeSupport"},"customer_trade_support":{"$ref":"#/components/schemas/CustomerTradeSupport"},"share_with_mdic":{"$ref":"#/components/schemas/BooleanInput"},"active":{"$ref":"#/components/schemas/BooleanInput"}}},"CustomerDocumentType":{"type":"string","enum":["cnpj","cpf","nif","none"]},"NoNifReason":{"type":["string","null"],"enum":["not_informed","exempt","not_required",null]},"Customer":{"type":"object","additionalProperties":false,"required":["id","document_type","document","no_nif_reason","name","email","phone","municipal_registration","related_party","anonymized_at","created_at","updated_at","address"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"document_type":{"$ref":"#/components/schemas/CustomerDocumentType"},"document":{"type":["string","null"]},"no_nif_reason":{"$ref":"#/components/schemas/NoNifReason"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"related_party":{"$ref":"#/components/schemas/RelatedParty"},"anonymized_at":{"description":"When the e-mail and phone were erased at the data subject's request.","$ref":"#/components/schemas/NullableDateTime"},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"address":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Address"}]}}},"CustomerInput":{"type":"object","additionalProperties":false,"properties":{"document_type":{"$ref":"#/components/schemas/CustomerDocumentType"},"document":{"type":["string","null"]},"no_nif_reason":{"$ref":"#/components/schemas/NoNifReason"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"municipal_registration":{"type":["string","null"]},"related_party":{"$ref":"#/components/schemas/RelatedParty"},"address":{"$ref":"#/components/schemas/AddressInput"}}},"PersonalData":{"type":"object","additionalProperties":false,"required":["customer","taxpayer","invoices","shared_with","generated_at"],"properties":{"customer":{"$ref":"#/components/schemas/Customer"},"taxpayer":{"description":"The controller of the data.","type":"object","additionalProperties":false,"required":["id","document_type","document","legal_name"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"document_type":{"type":"string","enum":["cnpj","cpf"]},"document":{"type":"string"},"legal_name":{"type":"string"}}},"invoices":{"description":"Invoices whose XML and DANFSe hold the data as sent at emission.","type":"array","items":{"type":"object","additionalProperties":false,"required":["id","status","series","dps_number","nfse_number","access_key","competence_date","authorized_at","retain_until","roles"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"series":{"type":"string"},"dps_number":{"type":"integer"},"nfse_number":{"type":["string","null"]},"access_key":{"type":["string","null"]},"competence_date":{"type":"string","format":"date"},"authorized_at":{"$ref":"#/components/schemas/NullableDateTime"},"retain_until":{"type":["string","null"],"format":"date","description":"Kept until this date by fiscal law."},"roles":{"type":"array","items":{"type":"string","enum":["customer","intermediary","recipient"]}}}}},"shared_with":{"type":"object","additionalProperties":false,"required":["sefin_nacional","webhook_endpoints"],"properties":{"sefin_nacional":{"type":"boolean","description":"The invoices went to Sefin Nacional and the ADN","by legal obligation.":null},"webhook_endpoints":{"description":"Active endpoints that receive the parties' personal data with invoice events.","type":"array","items":{"type":"object","additionalProperties":false,"required":["id","url","description"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]}}}}}},"generated_at":{"$ref":"#/components/schemas/DateTime"}}},"InvoiceStatus":{"type":"string","enum":["queued","transmitting","authorized","rejected","cancelled","substituted"]},"Tax":{"type":"object","additionalProperties":false,"description":"One tax of the invoice. `pis` and `cofins` can show twice: the own debt (`withheld: false`, with `cst`) and the customer's withholding (`withheld: true`). Withheld taxes come off `net_value`.","required":["tax","base","rate","reduction","amount","withheld","cst"],"properties":{"tax":{"type":"string","enum":["iss","cbs","ibs_state","ibs_municipal","pis","cofins","irrf","csll","inss"]},"base":{"$ref":"#/components/schemas/Decimal"},"rate":{"$ref":"#/components/schemas/Decimal"},"reduction":{"$ref":"#/components/schemas/NullableDecimal"},"amount":{"$ref":"#/components/schemas/Decimal"},"withheld":{"type":"boolean"},"cst":{"type":["string","null"]}}},"Invoice":{"allOf":[{"$ref":"#/components/schemas/InvoiceFields"}],"unevaluatedProperties":false},"InvoiceFields":{"type":"object","required":["id","taxpayer_id","status","kind","dps_number","dps_id","competence_date","issued_at","authorized_at","cancelled_at","substituted_invoice_id","substitute_invoice_id","service_id","customer_id","intermediary_id","recipient_id","description","final_consumer","iss_taxation","service_value","unconditional_discount","conditional_discount","net_value","iss_rate","approximate_federal_rate","approximate_state_rate","approximate_municipal_rate","simples_total_rate","access_key","nfse_number","public_url","created_at","updated_at","series","created_by","customer","supply_municipality","supply_country_code","foreign_trade","result_country_code","service","taxes"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"kind":{"type":"string","enum":["normal"]},"dps_number":{"type":"integer"},"dps_id":{"type":"string"},"competence_date":{"type":"string","format":"date"},"issued_at":{"$ref":"#/components/schemas/DateTime"},"authorized_at":{"$ref":"#/components/schemas/NullableDateTime"},"cancelled_at":{"$ref":"#/components/schemas/NullableDateTime","description":"When Sefin Nacional registered the cancellation or the substitution."},"substituted_invoice_id":{"type":["string","null"],"format":"uuid","description":"For a substitute","the invoice it replaces.":null},"substitute_invoice_id":{"type":["string","null"],"format":"uuid","description":"For a substituted invoice","the authorized invoice that replaced it.":null},"service_id":{"type":["string","null"],"format":"uuid"},"customer_id":{"$ref":"#/components/schemas/Uuid"},"intermediary_id":{"type":["string","null"],"format":"uuid"},"recipient_id":{"type":["string","null"],"format":"uuid"},"description":{"type":"string"},"final_consumer":{"type":"boolean"},"iss_taxation":{"$ref":"#/components/schemas/IssTaxation"},"service_value":{"$ref":"#/components/schemas/Decimal"},"unconditional_discount":{"$ref":"#/components/schemas/Decimal"},"conditional_discount":{"$ref":"#/components/schemas/Decimal"},"net_value":{"$ref":"#/components/schemas/Decimal"},"iss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_federal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_state_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_municipal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"simples_total_rate":{"$ref":"#/components/schemas/NullableDecimal"},"access_key":{"type":["string","null"],"description":"The 50-character NFS-e access key","after authorization.":null},"nfse_number":{"type":["string","null"]},"public_url":{"type":["string","null"],"description":"The public NFS-e page","after authorization.":null},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"series":{"type":"string"},"created_by":{"$ref":"#/components/schemas/CreatedBy"},"customer":{"type":"object","additionalProperties":false,"required":["id","name","document_type","document"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"document_type":{"$ref":"#/components/schemas/CustomerDocumentType"},"document":{"type":["string","null"]}}},"supply_municipality":{"$ref":"#/components/schemas/NullableMunicipalityRef"},"supply_country_code":{"type":["string","null"],"description":"Set for a place of supply abroad."},"foreign_trade":{"$ref":"#/components/schemas/ForeignTrade"},"result_country_code":{"type":["string","null"],"description":"cPaisResult: the country where the result of an exported service happens."},"service":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"}}}]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}}},"CreatedBy":{"description":"The account and user that emitted the invoice or requested the event. Null for records created before this field.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["account_name","user_name"],"properties":{"account_name":{"type":"string"},"user_name":{"type":["string","null"]}}}]},"InvoiceMessage":{"type":"object","additionalProperties":false,"required":["kind","source","code","description","complement"],"properties":{"kind":{"type":"string","enum":["error","alert"]},"source":{"type":"string","enum":["app","sefin"],"description":"`app` for a check before Sefin Nacional, `sefin` for its answer."},"code":{"type":"string"},"description":{"type":"string"},"complement":{"type":["string","null"]}}},"InvoiceDetail":{"allOf":[{"$ref":"#/components/schemas/InvoiceFields"}],"unevaluatedProperties":false,"required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceMessage"}}}},"InvoiceCorrectionInput":{"type":"object","additionalProperties":false,"description":"The fields to change. The série cannot change.","properties":{"service_id":{"type":["string","null"],"format":"uuid","description":"A catalog service; it gives the codes and the description template."},"customer_id":{"type":"string","format":"uuid","description":"The tomador."},"intermediary_id":{"type":["string","null"],"format":"uuid"},"recipient_id":{"type":["string","null"],"format":"uuid"},"competence_date":{"type":["string","null"],"format":"date","description":"Default today."},"description":{"type":["string","null"],"description":"Default the service's description template."},"service_value":{"$ref":"#/components/schemas/DecimalInput"},"unconditional_discount":{"$ref":"#/components/schemas/DecimalInput"},"conditional_discount":{"$ref":"#/components/schemas/DecimalInput"},"final_consumer":{"type":["boolean","string","null"]},"supply_municipality_ibge_code":{"type":["string","null"],"description":"Place of supply in Brazil. Default the taxpayer's municipality."},"supply_country_code":{"type":["string","null"],"description":"Place of supply abroad (ISO 3166-1 alpha-2)."},"currency_code":{"type":["string","null"],"examples":["USD"],"description":"ISO 4217. Required, with `foreign_service_value`, when the customer or intermediary address is abroad, the place of supply is abroad, or the service is an export. Ignored otherwise."},"foreign_service_value":{"$ref":"#/components/schemas/DecimalInput","description":"The service value in that currency. `service_value` stays in reais."},"result_country_code":{"type":["string","null"],"description":"Export with the place of supply in Brazil: the country where the result happens (ISO 3166-1 alpha-2). Default the customer's address country when abroad. Ignored otherwise."},"approximate_federal_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_state_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_municipal_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_total_rate":{"$ref":"#/components/schemas/DecimalInput"},"iss_rate":{"$ref":"#/components/schemas/DecimalInput","description":"ISS rate fraction (`pAliq`), used only when the DPS declares it: an ME/EPP with `simples_regime` `all_by_simples` whose customer withholds the ISS (default: the taxpayer's `simples_iss_rate`), or a municipality outside the national environment (default: the service's ISS rate)."},"retentions":{"$ref":"#/components/schemas/RetentionsInput"}}},"RetentionsInput":{"type":["object","null"],"additionalProperties":false,"description":"Federal taxes the customer withholds, as rate fractions. An omitted key takes the estimate: for a customer with a CNPJ, the service's `irrf_rate`, `csll_rate` and `inss_rate`, and PIS 0.0065 and COFINS 0.03 when the service has a `csll_rate`. `0` turns a withholding off. IRRF needs a taxpayer outside the Simples Nacional (`not_opted` or `none_by_simples`); CSLL, PIS and COFINS need a CNPJ there; PIS and COFINS end with competence 2027-01-01. A correction or a substitution keeps the rates of the original unless given.","properties":{"irrf_rate":{"$ref":"#/components/schemas/DecimalInput"},"csll_rate":{"$ref":"#/components/schemas/DecimalInput"},"pis_rate":{"$ref":"#/components/schemas/DecimalInput"},"cofins_rate":{"$ref":"#/components/schemas/DecimalInput"},"inss_rate":{"$ref":"#/components/schemas/DecimalInput"}}},"InvoiceInput":{"type":"object","additionalProperties":false,"properties":{"service_id":{"type":["string","null"],"format":"uuid","description":"A catalog service; it gives the codes and the description template."},"customer_id":{"type":"string","format":"uuid","description":"The tomador."},"intermediary_id":{"type":["string","null"],"format":"uuid"},"recipient_id":{"type":["string","null"],"format":"uuid"},"competence_date":{"type":["string","null"],"format":"date","description":"Default today."},"description":{"type":["string","null"],"description":"Default the service's description template."},"service_value":{"$ref":"#/components/schemas/DecimalInput"},"unconditional_discount":{"$ref":"#/components/schemas/DecimalInput"},"conditional_discount":{"$ref":"#/components/schemas/DecimalInput"},"final_consumer":{"type":["boolean","string","null"]},"supply_municipality_ibge_code":{"type":["string","null"],"description":"Place of supply in Brazil. Default the taxpayer's municipality."},"supply_country_code":{"type":["string","null"],"description":"Place of supply abroad (ISO 3166-1 alpha-2)."},"currency_code":{"type":["string","null"],"examples":["USD"],"description":"ISO 4217. Required, with `foreign_service_value`, when the customer or intermediary address is abroad, the place of supply is abroad, or the service is an export. Ignored otherwise."},"foreign_service_value":{"$ref":"#/components/schemas/DecimalInput","description":"The service value in that currency. `service_value` stays in reais."},"result_country_code":{"type":["string","null"],"description":"Export with the place of supply in Brazil: the country where the result happens (ISO 3166-1 alpha-2). Default the customer's address country when abroad. Ignored otherwise."},"approximate_federal_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_state_rate":{"$ref":"#/components/schemas/DecimalInput"},"approximate_municipal_rate":{"$ref":"#/components/schemas/DecimalInput"},"simples_total_rate":{"$ref":"#/components/schemas/DecimalInput"},"iss_rate":{"$ref":"#/components/schemas/DecimalInput","description":"ISS rate fraction (`pAliq`), used only when the DPS declares it: an ME/EPP with `simples_regime` `all_by_simples` whose customer withholds the ISS (default: the taxpayer's `simples_iss_rate`), or a municipality outside the national environment (default: the service's ISS rate)."},"retentions":{"$ref":"#/components/schemas/RetentionsInput"},"series":{"type":["string","null"],"description":"Default `00001`."}}},"InvoicePreview":{"type":"object","additionalProperties":false,"required":["competence_date","description","service_value","unconditional_discount","conditional_discount","net_value","iss_rate","approximate_federal_rate","approximate_state_rate","approximate_municipal_rate","simples_total_rate","series","iss_taxation","foreign_trade","result_country_code","taxes","warnings"],"properties":{"competence_date":{"type":"string","format":"date"},"description":{"type":"string"},"service_value":{"$ref":"#/components/schemas/Decimal"},"unconditional_discount":{"$ref":"#/components/schemas/Decimal"},"conditional_discount":{"$ref":"#/components/schemas/Decimal"},"net_value":{"$ref":"#/components/schemas/Decimal"},"iss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_federal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_state_rate":{"$ref":"#/components/schemas/NullableDecimal"},"approximate_municipal_rate":{"$ref":"#/components/schemas/NullableDecimal"},"simples_total_rate":{"$ref":"#/components/schemas/NullableDecimal"},"series":{"type":"string"},"iss_taxation":{"$ref":"#/components/schemas/IssTaxation"},"foreign_trade":{"$ref":"#/components/schemas/ForeignTrade"},"result_country_code":{"type":["string","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}},"warnings":{"type":"array","description":"`certificate_missing`, `certificate_expired`, or `federal_retention_below_minimum`: an IRRF, or a PIS + COFINS + CSLL withholding, of R$ 10 or less. The customer may skip it when its monthly total stays under R$ 10; send the rate as `0` to leave it out.","items":{"type":"string"}}}},"InvoiceStats":{"type":"object","additionalProperties":false,"required":["months","authorized_count","authorized_value"],"properties":{"months":{"type":"array","minItems":12,"maxItems":12,"items":{"type":"object","additionalProperties":false,"required":["month","authorized_count","authorized_value","rejected_count"],"properties":{"month":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$","examples":["2026-10"]},"authorized_count":{"type":"integer"},"authorized_value":{"$ref":"#/components/schemas/Decimal"},"rejected_count":{"type":"integer"}}}},"authorized_count":{"type":"integer"},"authorized_value":{"$ref":"#/components/schemas/Decimal"}}},"InvoiceImportStatus":{"type":"string","enum":["parsed","needs_review","learning","emitting","completed"]},"InvoiceImportRowState":{"type":"string","enum":["pending","selected","skipped","excluded","invoiced","duplicate","failed"]},"InvoiceImport":{"allOf":[{"$ref":"#/components/schemas/InvoiceImportFields"}],"unevaluatedProperties":false},"InvoiceImportFields":{"type":"object","required":["id","taxpayer_id","status","review_reason","file_name","page_count","payment_date","printed_total","extracted_total","row_count","ai_attempts","provider_code","provider_code_unconfirmed","customer_id","confirmed_at","completed_at","created_at","issuer"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/InvoiceImportStatus"},"review_reason":{"type":["string","null"],"enum":["no_layout","total_mismatch","provider_mismatch","no_rows","regex_timeout","customer_unavailable","personal_data_in_layout","learning_failed","learning_limit","learning_unavailable","issuer_unknown",null]},"file_name":{"type":"string"},"page_count":{"type":"integer"},"payment_date":{"type":["string","null"],"format":"date"},"printed_total":{"$ref":"#/components/schemas/NullableDecimal"},"extracted_total":{"$ref":"#/components/schemas/NullableDecimal"},"row_count":{"type":"integer"},"ai_attempts":{"type":"integer","description":"Layout learning attempts so far. The second attempt corrects the first."},"provider_code":{"type":["string","null"],"description":"The broker SUSEP code read from the statement."},"provider_code_unconfirmed":{"type":"boolean","description":"The statement has no broker CNPJ and its SUSEP code waits for confirmation; emission is blocked."},"customer_id":{"type":["string","null"],"format":"uuid","description":"The tomador of every invoice","the statement issuer. Null while the customer is only proposed.":null},"confirmed_at":{"$ref":"#/components/schemas/NullableDateTime"},"completed_at":{"$ref":"#/components/schemas/NullableDateTime"},"created_at":{"$ref":"#/components/schemas/DateTime"},"issuer":{"type":["object","null"],"additionalProperties":false,"required":["id","name","document"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"document":{"type":"string"}}}}},"InvoiceImportDetail":{"allOf":[{"$ref":"#/components/schemas/InvoiceImportFields"}],"unevaluatedProperties":false,"required":["row_counts","setup_errors","rows","proposed_customer","proposed_service","provider_taxpayer"],"properties":{"proposed_customer":{"type":["object","null"],"description":"The statement issuer, from the CNPJ lookup, not yet a customer. The emission adds it with `add_customer`.","additionalProperties":false,"required":["name","document"],"properties":{"name":{"type":"string"},"document":{"type":"string"}}},"proposed_service":{"type":["object","null"],"description":"The service of the settings area, not yet created. The emission adds it with `add_service`.","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string"}}},"provider_taxpayer":{"type":["object","null"],"description":"For `provider_mismatch`, another taxpayer you can reach whose CNPJ the statement prints. Send the file again under that taxpayer.","additionalProperties":false,"required":["id","name"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"}}},"row_counts":{"type":"object","additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/InvoiceImportRowState"}},"setup_errors":{"type":"array","items":{"$ref":"#/components/schemas/ProblemError"}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceImportRow"}}}},"InvoiceImportRow":{"type":"object","additionalProperties":false,"required":["id","position","state","row_type","reference","sub_reference","counterpart_name","counterpart_document","category","row_label","base_amount","rate","amount","date","extras","error_code","description","invoice","estimated_taxes"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"position":{"type":"integer"},"state":{"$ref":"#/components/schemas/InvoiceImportRowState"},"row_type":{"type":"string","enum":["normal","negative","bonus"]},"reference":{"type":["string","null"],"description":"Policy","guia or order number.":null},"sub_reference":{"type":["string","null"],"description":"Endorsement or similar."},"counterpart_name":{"type":["string","null"],"description":"The insured person or company. Personal data."},"counterpart_document":{"type":["string","null"]},"category":{"type":["string","null"],"description":"Ramo or similar."},"row_label":{"type":["string","null"]},"base_amount":{"$ref":"#/components/schemas/NullableDecimal"},"rate":{"$ref":"#/components/schemas/NullableDecimal"},"amount":{"$ref":"#/components/schemas/Decimal"},"date":{"type":["string","null"],"format":"date"},"extras":{"type":"object","additionalProperties":{"type":"string"}},"error_code":{"type":["string","null"]},"description":{"type":["string","null"],"description":"The invoice description from the settings template."},"invoice":{"type":["object","null"],"additionalProperties":false,"required":["id","status"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/InvoiceStatus"}}},"estimated_taxes":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["tax","rate","amount"],"properties":{"tax":{"type":"string","enum":["iss","cbs","ibs_state","ibs_municipal"]},"rate":{"$ref":"#/components/schemas/Decimal"},"amount":{"$ref":"#/components/schemas/Decimal"}}}}}},"StatementImportSettings":{"type":"object","additionalProperties":false,"required":["taxpayer_id","service_id","description_template","sector_code","preset","saved"],"properties":{"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"preset":{"type":["string","null"],"enum":["insurance",null],"description":"The service area whose service the settings use."},"service_id":{"type":["string","null"],"format":"uuid"},"description_template":{"type":["string","null"]},"sector_code":{"type":["string","null"],"description":"The broker's SUSEP code","checked when a statement prints no CNPJ.":null},"saved":{"type":"boolean"}}},"StatementImportSettingsInput":{"type":"object","additionalProperties":false,"properties":{"preset":{"type":"string","enum":["insurance"],"description":"Use the service of this area. Without one","the settings propose it":null,"and the first emission adds it.":null},"service_id":{"type":"string","format":"uuid"},"description_template":{"type":"string","maxLength":2000},"sector_code":{"type":["string","null"],"maxLength":20}}},"MunicipalParameters":{"type":"object","additionalProperties":false,"required":["municipality","nfse_nacional_active","nfse_nacional_checked_at","date","service_code","iss_rate"],"properties":{"municipality":{"$ref":"#/components/schemas/MunicipalityRef"},"nfse_nacional_active":{"type":["boolean","null"],"description":"Null when the ADN has not answered yet."},"nfse_nacional_checked_at":{"$ref":"#/components/schemas/NullableDateTime"},"date":{"type":"string","format":"date"},"service_code":{"type":["string","null"],"description":"The 9-digit code used for the rate."},"iss_rate":{"$ref":"#/components/schemas/NullableDecimal"}}},"CancellationInput":{"type":"object","additionalProperties":false,"required":["reason_code","reason_text"],"properties":{"reason_code":{"type":"string","enum":["1","2","9"],"description":"`cMotivo`: 1 issue error, 2 service not provided, 9 other."},"reason_text":{"type":"string","minLength":15,"maxLength":255,"description":"`xMotivo`."}}},"SubstitutionInput":{"type":"object","additionalProperties":false,"required":["reason_code"],"properties":{"reason_code":{"type":"string","enum":["01","02","03","04","05","99"],"description":"`cMotivo`: 01 leaves the Simples Nacional, 02 joins the Simples Nacional, 03 retroactive immunity or exemption, 04 immunity or exemption removed, 05 refused by the tomador or the intermediário, 99 other."},"reason_text":{"type":["string","null"],"minLength":15,"maxLength":255,"description":"`xMotivo`, optional."}}},"InvoiceEvent":{"type":"object","additionalProperties":false,"required":["id","invoice_id","event_type","status","reason_code","reason_text","sequence","registered_at","substitute_invoice_id","created_at","updated_at","created_by","messages"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"invoice_id":{"$ref":"#/components/schemas/Uuid"},"event_type":{"type":"string","enum":["101101","105102"],"description":"101101 cancellation, 105102 cancellation by substitution."},"status":{"type":"string","enum":["queued","transmitting","registered","rejected"]},"reason_code":{"type":"string"},"reason_text":{"type":["string","null"]},"sequence":{"type":["integer","null"],"description":"`nSeqEvento`, after registration."},"registered_at":{"$ref":"#/components/schemas/NullableDateTime"},"substitute_invoice_id":{"type":["string","null"],"format":"uuid","description":"The invoice that replaced this one (105102)."},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"created_by":{"$ref":"#/components/schemas/CreatedBy"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceMessage"}}}},"WebhookEventType":{"type":"string","enum":["invoice.authorized","invoice.rejected","invoice.cancelled","invoice.substituted","invoice_event.rejected","certificate.expiring","invoice_import.completed"]},"WebhookEndpoint":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpointFields"}],"unevaluatedProperties":false},"WebhookEndpointFields":{"type":"object","required":["id","url","description","event_types","active","include_personal_data","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"active":{"type":"boolean"},"include_personal_data":{"type":"boolean","description":"Adds the customer, recipient and intermediary (document, name, e-mail, phone, address) to invoice payloads, and the certificate subject document to certificate.expiring."},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"}}},"WebhookEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/WebhookEndpointFields"}],"unevaluatedProperties":false,"required":["secret"],"properties":{"secret":{"type":"string","description":"The signing secret. Store it; it is not shown again."}}},"WebhookEndpointInput":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","description":"A public HTTPS URL."},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"active":{"$ref":"#/components/schemas/BooleanInput"},"include_personal_data":{"$ref":"#/components/schemas/BooleanInput"}}},"WebhookDeliveryStatus":{"type":"string","enum":["pending","delivered","failed"]},"WebhookDelivery":{"allOf":[{"$ref":"#/components/schemas/WebhookDeliveryFields"}],"unevaluatedProperties":false},"WebhookDeliveryFields":{"type":"object","required":["id","webhook_endpoint_id","invoice_id","event_id","event_type","status","attempts","last_http_status","last_error","last_attempt_at","next_attempt_at","delivered_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"webhook_endpoint_id":{"$ref":"#/components/schemas/Uuid"},"invoice_id":{"type":["string","null"],"format":"uuid"},"event_id":{"$ref":"#/components/schemas/Uuid"},"event_type":{"type":"string","examples":["invoice.authorized","webhook.test"]},"status":{"$ref":"#/components/schemas/WebhookDeliveryStatus"},"attempts":{"type":"integer"},"last_http_status":{"type":["integer","null"]},"last_error":{"type":["string","null"],"examples":["timeout"]},"last_attempt_at":{"$ref":"#/components/schemas/NullableDateTime"},"next_attempt_at":{"$ref":"#/components/schemas/NullableDateTime"},"delivered_at":{"$ref":"#/components/schemas/NullableDateTime"},"created_at":{"$ref":"#/components/schemas/DateTime"}}},"WebhookDeliveryDetail":{"allOf":[{"$ref":"#/components/schemas/WebhookDeliveryFields"}],"unevaluatedProperties":false,"required":["payload"],"properties":{"payload":{"type":"object","description":"The event body as sent. See /docs/webhooks."}}},"WebhookEventFields":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"created_at":{"$ref":"#/components/schemas/DateTime"}}},"WebhookInvoicePayload":{"allOf":[{"$ref":"#/components/schemas/WebhookEventFields"}],"unevaluatedProperties":false,"properties":{"type":{"type":"string","enum":["invoice.authorized","invoice.rejected","invoice.cancelled","invoice.substituted"]},"data":{"type":"object","additionalProperties":false,"required":["invoice"],"properties":{"invoice":{"$ref":"#/components/schemas/WebhookInvoice"}}}}},"WebhookInvoiceEventPayload":{"allOf":[{"$ref":"#/components/schemas/WebhookEventFields"}],"unevaluatedProperties":false,"properties":{"type":{"const":"invoice_event.rejected"},"data":{"type":"object","additionalProperties":false,"required":["invoice","invoice_event"],"properties":{"invoice":{"$ref":"#/components/schemas/WebhookInvoice"},"invoice_event":{"type":"object","additionalProperties":false,"required":["id","event_type","status","reason_code","rejection_codes"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"event_type":{"type":"string","enum":["101101","105102"]},"status":{"type":"string","enum":["queued","transmitting","registered","rejected"]},"reason_code":{"type":"string"},"rejection_codes":{"type":"array","items":{"type":"string"}}}}}}}},"InvoiceReading":{"type":"object","additionalProperties":false,"required":["id","taxpayer_id","status","source","failure_code","file_name","expires_at","created_at","emitter","customer","service","invoice","warnings"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["reading","read","failed"]},"source":{"type":"string","enum":["national_xml","pdf_ai","statement","statement_ai"],"description":"Commission statements, only without `taxpayer_id`. `statement`: read with a stored layout, or only the broker CNPJ\nfound by its label. `statement_ai`: read by AI in the background, when neither finds the broker CNPJ.\n"},"failure_code":{"type":["string","null"],"enum":["refusal","max_tokens","invalid_json","reading_unavailable",null]},"file_name":{"type":["string","null"]},"expires_at":{"$ref":"#/components/schemas/DateTime"},"created_at":{"$ref":"#/components/schemas/DateTime"},"emitter":{"description":"The prestador. `null` until the reading is `read`.","type":["object","null"],"additionalProperties":false,"required":["document_type","document","name","municipal_registration","email","phone","simples_optant","address","match"],"properties":{"document_type":{"type":["string","null"],"enum":["cnpj","cpf",null]},"document":{"$ref":"#/components/schemas/InvoiceReadingText"},"name":{"$ref":"#/components/schemas/InvoiceReadingText"},"municipal_registration":{"$ref":"#/components/schemas/InvoiceReadingText"},"email":{"$ref":"#/components/schemas/InvoiceReadingText"},"phone":{"$ref":"#/components/schemas/InvoiceReadingText"},"simples_optant":{"type":["boolean","null"]},"simples_status":{"description":"Only from an XML (`opSimpNac`).","type":["string","null"],"enum":["not_opted","mei","me_epp",null]},"simples_regime":{"description":"Only from an XML (`regApTribSN`).","type":["string","null"],"enum":["all_by_simples","federal_by_simples","none_by_simples",null]},"address":{"$ref":"#/components/schemas/InvoiceReadingAddress"},"match":{"description":"The taxpayer of the account with the same document.","type":["object","null"],"additionalProperties":false,"required":["taxpayer_id"],"properties":{"taxpayer_id":{"$ref":"#/components/schemas/Uuid"}}}}},"customer":{"description":"The tomador. `null` when the invoice has none or the reading is not `read`.","type":["object","null"],"additionalProperties":false,"required":["document_type","document","no_nif_reason","name","email","phone","address","foreign_address","match"],"properties":{"document_type":{"type":"string","enum":["cnpj","cpf","nif","none"]},"document":{"$ref":"#/components/schemas/InvoiceReadingText"},"no_nif_reason":{"type":["string","null"],"enum":["not_informed","exempt","not_required",null]},"name":{"$ref":"#/components/schemas/InvoiceReadingText"},"email":{"$ref":"#/components/schemas/InvoiceReadingText"},"phone":{"$ref":"#/components/schemas/InvoiceReadingText"},"address":{"$ref":"#/components/schemas/InvoiceReadingAddress"},"foreign_address":{"type":["object","null"],"additionalProperties":false,"required":["street","number","complement","district","postal_code","city","region","country_code"],"properties":{"street":{"$ref":"#/components/schemas/InvoiceReadingText"},"number":{"$ref":"#/components/schemas/InvoiceReadingText"},"complement":{"$ref":"#/components/schemas/InvoiceReadingText"},"district":{"$ref":"#/components/schemas/InvoiceReadingText"},"postal_code":{"$ref":"#/components/schemas/InvoiceReadingText"},"city":{"$ref":"#/components/schemas/InvoiceReadingText"},"region":{"$ref":"#/components/schemas/InvoiceReadingText"},"country_code":{"$ref":"#/components/schemas/InvoiceReadingText"}}},"match":{"description":"The customer of the matched taxpayer with the same document, or, abroad without a document, the same name and country.","type":["object","null"],"additionalProperties":false,"required":["customer_id"],"properties":{"customer_id":{"$ref":"#/components/schemas/Uuid"}}}}},"service":{"type":["object","null"],"additionalProperties":false,"required":["description","national_service_code","nbs","iss_rate","iss_taxation","lc116_item","code_confirmed","match"],"properties":{"description":{"$ref":"#/components/schemas/InvoiceReadingText"},"national_service_code":{"type":["string","null"],"pattern":"^[0-9]{6}$"},"nbs":{"type":["string","null"],"pattern":"^[0-9]{9}$"},"iss_rate":{"$ref":"#/components/schemas/NullableDecimal"},"iss_taxation":{"type":["string","null"],"enum":["taxable","immune","export","non_incidence",null]},"lc116_item":{"type":["string","null"],"examples":["01.01"]},"code_confirmed":{"type":"boolean","description":"The national service code is in the file. When false, the code was found from the LC 116 item and the description; ask the user to confirm it."},"match":{"description":"An active service of the matched taxpayer with the same national service code and the closest description.","type":["object","null"],"additionalProperties":false,"required":["service_id"],"properties":{"service_id":{"$ref":"#/components/schemas/Uuid"}}}}},"invoice":{"type":["object","null"],"additionalProperties":false,"required":["amount","description","competence","iss_withholding","export"],"properties":{"amount":{"$ref":"#/components/schemas/NullableDecimal"},"description":{"$ref":"#/components/schemas/InvoiceReadingText"},"competence":{"type":["string","null"],"format":"date"},"iss_withholding":{"type":["string","null"],"enum":["not_withheld","by_customer","by_intermediary",null]},"export":{"description":"The foreign trade group of a national XML. `null` for a PDF.","type":["object","null"],"additionalProperties":false,"required":["supply_mode","related_party","currency","foreign_amount","provider_trade_support","customer_trade_support","share_with_mdic"],"properties":{"supply_mode":{"type":["string","null"]},"related_party":{"type":["string","null"]},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$"},"foreign_amount":{"$ref":"#/components/schemas/NullableDecimal"},"provider_trade_support":{"type":["string","null"]},"customer_trade_support":{"type":["string","null"]},"share_with_mdic":{"type":"boolean"}}}}},"warnings":{"type":"array","description":"`homologation_invoice` (an XML from the test environment); for a PDF, values dropped because the text does not show them:\n`emitter_document_unverified`, `customer_document_unverified`, `amount_unverified`. For an XML whose emitter matches a taxpayer,\ncomputed at each read: `simples_status_differs`, `simples_regime_differs` (the invoice has another Simples Nacional status or regime).\n","items":{"type":"string","enum":["homologation_invoice","emitter_document_unverified","customer_document_unverified","amount_unverified","simples_status_differs","simples_regime_differs"]}},"statement":{"description":"Only for `source` `statement` and `statement_ai` once read. The emitter is the broker (`null` when the statement prints\nonly the SUSEP code or no broker CNPJ is found), the customer is the insurer (`null` when its CNPJ is unknown), the service is `null`.\n","type":"object","additionalProperties":false,"required":["layout_known","provider_code","row_count","total","payment_date"],"properties":{"layout_known":{"type":"boolean","description":"`true`: a stored layout read the statement. `false`: a new format; the statement import learns it later."},"provider_code":{"type":["string","null"]},"row_count":{"type":["integer","null"]},"total":{"$ref":"#/components/schemas/NullableDecimal"},"payment_date":{"type":["string","null"],"format":"date"}}}}},"InvoiceReadingText":{"type":["string","null"]},"InvoiceReadingAddress":{"type":["object","null"],"additionalProperties":false,"required":["street","number","complement","district","postal_code","municipality_ibge_code"],"properties":{"street":{"$ref":"#/components/schemas/InvoiceReadingText"},"number":{"$ref":"#/components/schemas/InvoiceReadingText"},"complement":{"$ref":"#/components/schemas/InvoiceReadingText"},"district":{"$ref":"#/components/schemas/InvoiceReadingText"},"postal_code":{"type":["string","null"],"pattern":"^[0-9]{8}$"},"municipality_ibge_code":{"type":["string","null"],"pattern":"^[0-9]{7}$"}}},"WebhookCertificatePayload":{"allOf":[{"$ref":"#/components/schemas/WebhookEventFields"}],"unevaluatedProperties":false,"properties":{"type":{"const":"certificate.expiring"},"data":{"type":"object","additionalProperties":false,"required":["certificate"],"properties":{"certificate":{"type":"object","additionalProperties":false,"required":["id","taxpayer_id","not_after","days_left"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"not_after":{"$ref":"#/components/schemas/DateTime"},"days_left":{"type":"integer","enum":[30,15,7,1,0]},"subject_document":{"type":"string","description":"The taxpayer CNPJ or CPF. Only when the endpoint has include_personal_data."}}}}}}},"WebhookInvoiceImportPayload":{"allOf":[{"$ref":"#/components/schemas/WebhookEventFields"}],"unevaluatedProperties":false,"properties":{"type":{"const":"invoice_import.completed"},"data":{"type":"object","additionalProperties":false,"required":["invoice_import"],"properties":{"invoice_import":{"type":"object","additionalProperties":false,"required":["id","taxpayer_id","status","issuer","row_counts","printed_total","emitted_total","completed_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"status":{"const":"completed"},"issuer":{"type":"object","additionalProperties":false,"required":["name","document"],"properties":{"name":{"type":"string"},"document":{"type":"string"}}},"row_counts":{"type":"object","additionalProperties":{"type":"integer"},"propertyNames":{"$ref":"#/components/schemas/InvoiceImportRowState"}},"printed_total":{"$ref":"#/components/schemas/NullableDecimal"},"emitted_total":{"$ref":"#/components/schemas/Decimal"},"completed_at":{"$ref":"#/components/schemas/DateTime"}}}}}}},"WebhookTestPayload":{"allOf":[{"$ref":"#/components/schemas/WebhookEventFields"}],"unevaluatedProperties":false,"properties":{"type":{"const":"webhook.test"},"data":{"type":"object","additionalProperties":false,"required":["webhook_endpoint_id"],"properties":{"webhook_endpoint_id":{"$ref":"#/components/schemas/Uuid"}}}}},"WebhookInvoice":{"type":"object","additionalProperties":false,"required":["id","taxpayer_id","status","dps_id","dps_number","series","competence_date","service_value","net_value","access_key","nfse_number","authorized_at","cancelled_at","substituted_invoice_id","substitute_invoice_id","public_url","created_by","rejection_codes","customer"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"taxpayer_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"dps_id":{"type":"string"},"dps_number":{"type":"integer"},"series":{"type":"string","examples":["00001"]},"competence_date":{"type":"string","format":"date"},"service_value":{"$ref":"#/components/schemas/Decimal"},"net_value":{"$ref":"#/components/schemas/Decimal"},"access_key":{"type":["string","null"]},"nfse_number":{"type":["string","null"]},"authorized_at":{"$ref":"#/components/schemas/NullableDateTime"},"cancelled_at":{"$ref":"#/components/schemas/NullableDateTime"},"substituted_invoice_id":{"type":["string","null"],"format":"uuid"},"substitute_invoice_id":{"type":["string","null"],"format":"uuid"},"public_url":{"type":["string","null"]},"created_by":{"description":"The account and user that emitted the invoice. `user_name` only with include_personal_data.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["account_name","user_name"],"properties":{"account_name":{"type":"string"},"user_name":{"type":["string","null"]}}}]},"rejection_codes":{"type":"array","items":{"type":"string"},"examples":[["E0312"]]},"customer":{"description":"Only the id, unless the endpoint has include_personal_data.","oneOf":[{"$ref":"#/components/schemas/WebhookPartyRef"},{"$ref":"#/components/schemas/WebhookParty"}]},"recipient":{"$ref":"#/components/schemas/WebhookParty","description":"Only with include_personal_data","when the invoice has a recipient.":null},"intermediary":{"$ref":"#/components/schemas/WebhookParty","description":"Only with include_personal_data","when the invoice has an intermediary.":null}}},"WebhookPartyRef":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"}}},"WebhookParty":{"type":"object","additionalProperties":false,"required":["id","document_type","document","name","email","phone","address"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"document_type":{"$ref":"#/components/schemas/CustomerDocumentType"},"document":{"type":["string","null"]},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"address":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Address"}]}}},"Country":{"type":"object","additionalProperties":false,"required":["code","name"],"properties":{"code":{"type":"string","examples":["BR"]},"name":{"type":"string"}}},"Currency":{"type":"object","additionalProperties":false,"required":["iso_code","numeric_code","name"],"properties":{"iso_code":{"type":"string","examples":["USD"]},"numeric_code":{"type":"string","examples":["840"],"description":"ISO 4217 numeric code; the DPS sends it in tpMoeda."},"name":{"type":"string","description":"ISO 4217 name","in English.":null}}},"State":{"type":"object","additionalProperties":false,"required":["uf","ibge_code","name"],"properties":{"uf":{"type":"string"},"ibge_code":{"type":"string"},"name":{"type":"string"}}},"MunicipalityRow":{"type":"object","additionalProperties":false,"required":["id","ibge_code","name","uf"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"ibge_code":{"type":"string"},"name":{"type":"string"},"uf":{"type":"string"}}},"NationalServiceCode":{"type":"object","additionalProperties":false,"required":["id","code","lc116_item","description","iss_incidence"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string","examples":["010101"]},"lc116_item":{"type":"string","examples":["01.01"]},"description":{"type":"string"},"iss_incidence":{"type":["string","null"],"enum":["provider","place_of_supply","customer",null],"description":"Where the ISS falls due (Anexo I, MUN.INCID_INFO.SERV.). An export is not allowed for `place_of_supply` with the place of supply in Brazil, nor for `customer` with a customer in Brazil."}}},"NbsCode":{"type":"object","additionalProperties":false,"required":["id","code","formatted_code","description"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string","examples":["115021000"]},"formatted_code":{"type":"string","examples":["1.1502.10.00"]},"description":{"type":"string"}}},"OperationIndicator":{"type":"object","additionalProperties":false,"required":["id","code","operation_type","description","place_of_supply_rule","legal_basis"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string"},"operation_type":{"type":"string"},"description":{"type":"string"},"place_of_supply_rule":{"type":["string","null"]},"legal_basis":{"type":"string"}}},"TaxClassification":{"type":"object","additionalProperties":false,"required":["id","cst","cst_description","code","description","rate_type","legal_basis","cbs_reduction","ibs_state_reduction","ibs_municipal_reduction","valid_from","valid_to"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"cst":{"type":"string"},"cst_description":{"type":"string"},"code":{"type":"string"},"description":{"type":"string"},"rate_type":{"type":"string"},"legal_basis":{"type":["string","null"]},"cbs_reduction":{"$ref":"#/components/schemas/Decimal"},"ibs_state_reduction":{"$ref":"#/components/schemas/Decimal"},"ibs_municipal_reduction":{"$ref":"#/components/schemas/Decimal"},"valid_from":{"type":"string","format":"date"},"valid_to":{"type":["string","null"],"format":"date"}}},"PostalCode":{"type":"object","additionalProperties":false,"required":["postal_code","street","district","municipality"],"properties":{"postal_code":{"type":"string"},"street":{"type":["string","null"]},"district":{"type":["string","null"]},"municipality":{"$ref":"#/components/schemas/NullableMunicipalityRef"}}},"Company":{"type":"object","additionalProperties":false,"required":["cnpj","legal_name","trade_name","registration_status","head_office","main_activity","simples_status","email","phone","address"],"properties":{"cnpj":{"type":"string"},"legal_name":{"type":["string","null"]},"trade_name":{"type":["string","null"]},"registration_status":{"type":["string","null"],"enum":["active","suspended","unfit","closed","null",null],"description":"Receita Federal status. The string `null` is the registry's own \"nula\" status."},"head_office":{"type":"boolean"},"main_activity":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["cnae","description"],"properties":{"cnae":{"type":"string","examples":["6201501"]},"description":{"type":["string","null"]}}}]},"simples_status":{"type":"string","enum":["mei","me_epp","not_opted"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"address":{"type":"object","additionalProperties":false,"required":["postal_code","street","number","complement","district","municipality"],"properties":{"postal_code":{"type":["string","null"]},"street":{"type":["string","null"]},"number":{"type":["string","null"]},"complement":{"type":["string","null"]},"district":{"type":["string","null"]},"municipality":{"$ref":"#/components/schemas/NullableMunicipalityRef"}}}}}}}}