> ## 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. # Register the inbound NF-e issued for a return (Brazil) > Brazil only, for stores whose NF-e are issued through Cubbo's fiscal provider. After your store issues the inbound NF-e (*Nota Fiscal Eletrônica de entrada*) for a returned order, call this endpoint with the invoice references so Cubbo can link them to the return and fetch the authorized document. Each item is linked according to its `purpose`: - `RETURN_INVOICE`: the NF-e that documents the goods coming back from the customer; linked to the return. - `REPLENISHMENT_INVOICE`: the NF-e that documents the stock re-entering the warehouse; linked to the return's stock re-entry (`replenishment_id` in the awaiting-invoice list). Behaviors: - The return's stock re-entry must be in the put-away stage (the same condition that lists it under `GET /returns/awaiting-invoice`); otherwise 422. - If every `key` you send is already registered, nothing is created: Cubbo re-syncs the existing invoices and answers 200 with `new_invoice_ids: []` and the matched keys in `update_invoice_ids`. - An `identifier` that is already used by a non-cancelled invoice is rejected (422). You may reuse an identifier whose previous invoice was cancelled. - Duplicate keys or identifiers within the same request are rejected (422). - Invoices are stored as pre-approved and confirmed asynchronously with the fiscal provider. - Your API credentials need the permission to update orders. ## OpenAPI ````yaml /openapi.yaml post /returns/{return_id}/attach-invoice 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: /returns/{return_id}/attach-invoice: post: tags: - Returns summary: Register the inbound NF-e issued for a return (Brazil) description: > Brazil only, for stores whose NF-e are issued through Cubbo's fiscal provider. After your store issues the inbound NF-e (*Nota Fiscal Eletrônica de entrada*) for a returned order, call this endpoint with the invoice references so Cubbo can link them to the return and fetch the authorized document. Each item is linked according to its `purpose`: - `RETURN_INVOICE`: the NF-e that documents the goods coming back from the customer; linked to the return. - `REPLENISHMENT_INVOICE`: the NF-e that documents the stock re-entering the warehouse; linked to the return's stock re-entry (`replenishment_id` in the awaiting-invoice list). Behaviors: - The return's stock re-entry must be in the put-away stage (the same condition that lists it under `GET /returns/awaiting-invoice`); otherwise 422. - If every `key` you send is already registered, nothing is created: Cubbo re-syncs the existing invoices and answers 200 with `new_invoice_ids: []` and the matched keys in `update_invoice_ids`. - An `identifier` that is already used by a non-cancelled invoice is rejected (422). You may reuse an identifier whose previous invoice was cancelled. - Duplicate keys or identifiers within the same request are rejected (422). - Invoices are stored as pre-approved and confirmed asynchronously with the fiscal provider. - Your API credentials need the permission to update orders. operationId: attachReturnInvoice parameters: - name: return_id in: path required: true description: Numeric id of the return. schema: type: integer example: 98765 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReturnAttachInvoiceRequest' example: invoices: - key: '00000000000000000000000000000000000000000000' identifier: RET-98765-M purpose: RETURN_INVOICE operation_type: ENTRADA operation_nature: Retorno de mercadoria nao entregue total_value: '116.56' responses: '200': description: Invoices registered (or already present and re-synced). content: application/json: schema: $ref: '#/components/schemas/ReturnAttachInvoiceResult' examples: created: value: new_invoice_ids: - 880001 alreadyRegistered: value: new_invoice_ids: [] update_invoice_ids: '00000000000000000000000000000000000000000000' '401': $ref: '#/components/responses/Unauthorized' '422': description: Validation or business error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingInvoices: value: error: Parameter invoices is required badKey: value: error: Parameter key must contain numbers only badPurpose: value: error: >- Parameter purpose must be within ["RETURN_INVOICE", "REPLENISHMENT_INVOICE"] badOperationType: value: error: Parameter operation_type must be within ["ENTRADA"] unsupportedInvoiceType: value: error: only WEBMANIA is supported for now returnNotFound: value: error: Couldn't find Return with 'id'=98765 notInPutaway: value: error: >- replenishment id 77001 of return id 98765 is not in putaway status, status is RECEIVED duplicateIdentifiers: value: error: 'duplicate invoice identifiers provided: ["RET-98765-M"]' duplicateKeys: value: error: >- duplicate invoice keys provided: ["00000000000000000000000000000000000000000000"] identifierExists: value: error: 'some identifiers provided already exist: ["RET-98765-M"]' providerError: value: error: 'WebmaniaError: ' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: schemas: ReturnAttachInvoiceRequest: type: object required: - invoices properties: invoice_type: type: string description: >- Fiscal provider the invoice was issued through. Only `WEBMANIA` is accepted today. enum: - WEBMANIA default: WEBMANIA example: WEBMANIA invoices: type: array description: >- Invoices to link to the return. Keys and identifiers must be unique within the request. minItems: 1 items: type: object required: - key - identifier - purpose - operation_type - operation_nature - total_value properties: key: type: string description: 44-digit NF-e access key (digits only). pattern: ^[0-9]{44}$ example: '00000000000000000000000000000000000000000000' identifier: type: string description: >- Your unique identifier for this invoice. Must not be in use by another non-cancelled invoice. example: RET-98765-M purpose: type: string description: >- `RETURN_INVOICE` links the invoice to the return; `REPLENISHMENT_INVOICE` links it to the return's stock re-entry. enum: - RETURN_INVOICE - REPLENISHMENT_INVOICE example: RETURN_INVOICE operation_type: type: string description: NF-e operation type; inbound only. enum: - ENTRADA example: ENTRADA operation_nature: type: string description: >- Nature of the operation (*natureza da operação*) as printed on the NF-e. example: Retorno de mercadoria nao entregue total_value: type: string description: Total value of the invoice, as a decimal string. example: '116.56' ReturnAttachInvoiceResult: type: object required: - new_invoice_ids properties: new_invoice_ids: type: array description: >- Ids of the invoices created by this call; empty when every key was already registered. items: type: integer example: - 880001 update_invoice_ids: type: string description: >- Only present when nothing was created. Comma-separated access keys of the already-registered invoices that were re-synced. example: '00000000000000000000000000000000000000000000' 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 responses: Unauthorized: description: >- Missing or invalid token, wrong credentials, or no access to the requested store. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidToken: value: error: Unauthorized message: invalid token noHeader: value: error: Unauthorized message: no authorization header found storeNotAllowed: value: error: Unauthorized message: not allowed to show? this Store 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.