> ## Documentation Index > Fetch the complete documentation index at: https://developers.cubbo.com/llms.txt > Use this file to discover all available pages before exploring further. # Provision the store's fiscal account (Brazil) > Brazil only. Creates the store's electronic invoicing account and registers its company data so the store can later upload a digital certificate and issue NF-e (Nota Fiscal Eletronica, the Brazilian electronic invoice). The store is derived from the credential used to obtain the token; no store id is accepted. - Idempotent: if the store already has a fiscal account, the account is not created again; the company data is re-sent and `status` comes back as `updated` instead of `created`. Retrying after a partial failure is safe. - The company data is also copied onto the store's own fiscal fields (the ones `PATCH /store` edits), but only where they are still blank. `mirrored_fields` lists what was written; `skipped_fields` lists what already had a value and was left alone. - `cnpj` and `tax_regime` are identity fields: if the store already holds a different value for either (from an earlier call or from `PATCH /store`), the request is rejected instead of overwriting it. Resubmitting the same value is not a conflict. For this reason, call this endpoint before setting those fields through `PATCH /store`. - `address.state` must be a two-letter Brazilian UF code; it is validated before the account is created. - The CNPJ (Cadastro Nacional da Pessoa Juridica, the Brazilian company tax id) is accepted with or without punctuation and stored on the store as digits only. - Provider credentials are never returned. ## OpenAPI ````yaml /openapi.yaml post /store/fiscal-account openapi: 3.1.0 info: title: Cubbo Clients API version: '1.0' summary: >- Orders, inventory, replenishments, returns, shipping and webhooks for Cubbo fulfillment. description: > The Cubbo Clients API connects your store, ERP or marketplace with Cubbo's fulfillment network. All endpoints except `POST /auth/token` require a bearer token; see the Authentication guide. Request and response bodies are JSON. Errors are JSON objects with an `error` key. contact: name: Cubbo integrations email: integraciones@cubbo.com servers: - url: https://api.cubbo.com/v1 description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange client credentials for a bearer token. - name: Orders description: Create, update, hold, cancel and read sales orders. - name: Shipping labels description: Read the shipping labels generated for an order. - name: Inventory description: Products and stock per store. - name: Lots description: Lot-level inventory for products with expiration or batch tracking. - name: Reports description: Bulk reports for reconciliation. - name: Replenishments description: Inbound shipments to the warehouse. - name: Returns description: Returns and exchanges. - name: Stores description: Store provisioning and settings. - name: Shipping methods description: Available shipping methods, coverage and quotes. - name: Click and collect description: Pickup points and in-store pickup orders. paths: /store/fiscal-account: post: tags: - Stores summary: Provision the store's fiscal account (Brazil) description: > Brazil only. Creates the store's electronic invoicing account and registers its company data so the store can later upload a digital certificate and issue NF-e (Nota Fiscal Eletronica, the Brazilian electronic invoice). The store is derived from the credential used to obtain the token; no store id is accepted. - Idempotent: if the store already has a fiscal account, the account is not created again; the company data is re-sent and `status` comes back as `updated` instead of `created`. Retrying after a partial failure is safe. - The company data is also copied onto the store's own fiscal fields (the ones `PATCH /store` edits), but only where they are still blank. `mirrored_fields` lists what was written; `skipped_fields` lists what already had a value and was left alone. - `cnpj` and `tax_regime` are identity fields: if the store already holds a different value for either (from an earlier call or from `PATCH /store`), the request is rejected instead of overwriting it. Resubmitting the same value is not a conflict. For this reason, call this endpoint before setting those fields through `PATCH /store`. - `address.state` must be a two-letter Brazilian UF code; it is validated before the account is created. - The CNPJ (Cadastro Nacional da Pessoa Juridica, the Brazilian company tax id) is accepted with or without punctuation and stored on the store as digits only. - Provider credentials are never returned. operationId: provisionStoreFiscalAccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FiscalAccountRequest' example: cnpj: 00.000.000/0001-91 legal_name: Partner Store SP LTDA trade_name: Partner Store state_registration: '123456789' tax_regime: SIMPLES_NACIONAL unit_type: matriz email: fiscal@example.com address: zip_code: 01310-100 street: Av. Paulista number: '1000' complement: Sala 1 neighborhood: Bela Vista city: Sao Paulo state: SP responses: '200': description: Fiscal account provisioned (or updated) and company data registered content: application/json: schema: $ref: '#/components/schemas/FiscalAccountResponse' example: store_id: 4821 fiscal_account: status: created cnpj: 00.000.000/0001-91 legal_name: Partner Store SP LTDA tax_regime: SIMPLES_NACIONAL mirrored_fields: - tax_id - tax_company_name - tax_state_registration - tax_regime - tax_address - tax_address_number - tax_address_neighborhood - tax_city - tax_zipcode - state skipped_fields: [] mirror_error: null '401': description: Missing or invalid token, or the credential is not bound to a store content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' example: error: Unauthorized message: credential is not bound to a store '422': description: Validation or business error content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingCnpj: value: error: Parameter cnpj is required missingAddress: value: error: address is required invalidTaxRegime: value: error: >- tax_regime must be one of: SIMPLES_NACIONAL, LUCRO_REAL, LUCRO_PRESUMIDO. invalidUnitType: value: error: 'unit_type must be one of: matriz, filial.' invalidState: value: error: >- address.state must be a two-letter Brazilian UF code (e.g. SP). identityConflict: value: error: >- tax_regime already set on this store to a different value. Update it with PATCH /v1/store first, or submit the value already on record. rejectedByProvider: value: error: >- The fiscal registration was rejected. Check the CNPJ, state registration, address, and tax regime. '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: FiscalAccountRequest: type: object required: - cnpj - legal_name - tax_regime - address properties: cnpj: type: string description: >- Company CNPJ, with or without punctuation. Stored on the store as digits only. example: 00.000.000/0001-91 legal_name: type: string description: Legal company name (razao social) example: Partner Store SP LTDA trade_name: type: string description: Trade name (nome fantasia) example: Partner Store state_registration: type: string description: State registration number (Inscricao Estadual) example: '123456789' tax_regime: type: string description: Brazilian tax regime; case-insensitive enum: - SIMPLES_NACIONAL - LUCRO_REAL - LUCRO_PRESUMIDO example: SIMPLES_NACIONAL unit_type: type: string description: >- Whether this CNPJ is the head office (`matriz`) or a branch (`filial`) enum: - matriz - filial default: matriz example: matriz email: type: string format: email description: Contact email for the fiscal account example: fiscal@example.com address: $ref: '#/components/schemas/FiscalAddress' FiscalAccountResponse: type: object required: - store_id - fiscal_account properties: store_id: type: integer description: Id of the store the account belongs to example: 4821 fiscal_account: type: object required: - status - cnpj - legal_name - tax_regime - mirrored_fields - skipped_fields - mirror_error properties: status: type: string description: >- `created` on the first call, `updated` when the account already existed enum: - created - updated example: created cnpj: type: string description: CNPJ as submitted example: 00.000.000/0001-91 legal_name: type: string description: Legal company name as submitted example: Partner Store SP LTDA tax_regime: type: string description: Tax regime, normalized to upper case enum: - SIMPLES_NACIONAL - LUCRO_REAL - LUCRO_PRESUMIDO example: SIMPLES_NACIONAL mirrored_fields: type: array description: Store fields filled from this request (they were blank before) items: type: string example: - tax_id - tax_company_name - tax_regime - tax_address - state skipped_fields: type: array description: Store fields that already had a value and were left unchanged items: type: string example: [] mirror_error: type: - string - 'null' description: >- Null normally. Set when the account was provisioned but the data could not be copied onto the store; contact Cubbo support. example: null UnauthorizedError: type: object description: Body of every 401 response properties: error: type: string description: Always `Unauthorized` example: Unauthorized message: type: string description: Why the request was refused example: invalid token required: - error - message Error: type: object description: Error body returned by every failed request. required: - error properties: error: type: string description: >- Human-readable description of the failure. For `401` responses it is always `Unauthorized`. example: Parameter store_id is required message: type: string description: >- Present on `401` responses only; the reason the request was rejected. example: invalid token code: type: - string - 'null' description: >- Stable machine-readable code, present on some order, return and replenishment errors. example: ORDER_ALREADY_EXISTS context: type: - object - 'null' description: >- Extra data about the failure when available, for example the id of the conflicting order. additionalProperties: true example: order_id: 987654 FiscalAddress: type: object description: Fiscal address of the company properties: zip_code: type: string description: Postal code (CEP) example: 01310-100 street: type: string description: Street example: Av. Paulista number: type: string description: Number example: '1000' complement: type: string description: Address complement example: Sala 1 neighborhood: type: string description: Neighborhood example: Bela Vista city: type: string description: City example: Sao Paulo state: type: string description: Two-letter Brazilian UF code; case-insensitive example: SP responses: InternalServerError: description: >- Unexpected error. Retry with backoff; if it persists, send the timestamp to Cubbo support. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'unexpected error, timestamp: 1760000000' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Token returned by `POST /auth/token`, sent as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.