Envia.com DC E API

openapi: 3.2.0
info:
  title: Envia Queries DC E API
  version: v2.3.1
  description: Read-only service for lookups, lists, and account utilities. This API provides access to countries, states, cities, carriers, services, and address structure information needed for shipping operations. Use this API to get the required information for building shipping forms and validating addresses. The Queries API is designed for developers who need read-only access to reference data such as supported carriers, available services, shipment history, and user account settings. It serves as the lookup layer of the Envia platform, enabling applications to populate dropdowns, validate inputs, and retrieve shipment details without modifying any data.
  contact:
    name: Envia API Support
    url: https://docs.envia.com/discuss
  license:
    name: Proprietary
    url: https://www.envia.com/terminos-y-condiciones
  termsOfService: https://www.envia.com/terminos-y-condiciones
servers:
- url: https://queries.test.envia.com/
  description: Sandbox/Test
- url: https://queries.envia.com/
  description: Production
security:
- bearerAuth: []
tags:
- name: DC-e
  description: Brazil DC-e (Declaração de Conteúdo Eletrônica) management operations
paths:
  /dce/autorizar:
    post:
      tags:
      - DC-e
      summary: Generate DC-e
      description: Authorize a DC-e with the /dce/autorizar endpoint and see request and response examples.
      operationId: generate-dce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emit
              - dest
              - produtos
              - transp
              properties:
                ide:
                  type: object
                  description: DC-e identification. Provide the emitter's state using either `uf` (abbreviation) or `cUF` (numeric IBGE code)
                  properties:
                    uf:
                      type: string
                      description: State abbreviation of the emitter. Converted to numeric IBGE code internally. Either `uf` or `cUF` must be provided
                      example: SP
                    cUF:
                      type: string
                      description: Numeric IBGE state code of the emitter (2 digits). Alternative to `uf`
                      example: '35'
                emit:
                  type: object
                  description: Emitter (sender) information — the person or company shipping the package
                  required:
                  - xNome
                  properties:
                    CNPJ:
                      type: string
                      description: Emitter CNPJ (14 digits). Dots, slashes, and dashes are removed automatically. Required if CPF is not provided
                    CPF:
                      type: string
                      description: Emitter CPF for individuals (11 digits). Required if CNPJ is not provided
                    xNome:
                      type: string
                      description: Emitter legal name or full name (2-60 chars). Must not have leading or trailing spaces — SEFAZ rejects with cStat=215
                      example: JOAO DA SILVA
                    endereco:
                      type: object
                      description: Emitter address. If not provided, the address will be reported to FAZENDA as N/A
                      required:
                      - logradouro
                      - numero
                      - bairro
                      - uf
                      - cep
                      properties:
                        logradouro:
                          type: string
                          description: Street name (2-60 chars)
                          example: Rua Henri Dunant
                        numero:
                          type: string
                          description: Street number (1-60 chars)
                        complemento:
                          type: string
                          description: Address complement — apartment, suite, etc. (1-60 chars)
                        bairro:
                          type: string
                          description: Neighborhood (2-60 chars). Use 'N/A' if not applicable — cannot be empty
                        municipio:
                          type: string
                          description: Municipality name. Resolved to IBGE code automatically. Required if `cod_municipio` is not provided
                        cod_municipio:
                          type: string
                          description: 7-digit IBGE municipality code. Required if `municipio` is not provided
                        uf:
                          type: string
                          description: State abbreviation (2 chars)
                          example: SP
                        cep:
                          type: string
                          description: Postal code (CEP, 8 digits, no dashes)
                          example: '01310100'
                        telefone:
                          type: string
                          description: Phone number with area code (6-14 chars)
                dest:
                  type: object
                  description: Recipient information
                  properties:
                    CNPJ:
                      type: string
                      description: Recipient CNPJ (14 digits). Required if CPF is not provided
                    CPF:
                      type: string
                      description: Recipient CPF for individuals (11 digits). Required if CNPJ is not provided
                    xNome:
                      type: string
                      description: Recipient name (2-60 chars). In homologation (tpAmb=2) SEFAZ overrides this with 'DCE EMITIDA EM AMBIENTE DE HOMOLOGACAO'
                      example: MARIA OLIVEIRA
                    endereco:
                      type: object
                      description: Recipient address. Same structure as emit.endereco. If not provided, the address will be reported to FAZENDA as N/A
                      required:
                      - logradouro
                      - numero
                      - bairro
                      - uf
                      - cep
                      properties:
                        logradouro:
                          type: string
                          description: Street name (2-60 chars)
                          example: Avenida Engenheiro Luiz Carlos Berrini
                        numero:
                          type: string
                          description: Street number (1-60 chars)
                        complemento:
                          type: string
                          description: Address complement — apartment, suite, etc. (1-60 chars)
                        bairro:
                          type: string
                          description: Neighborhood (2-60 chars)
                        municipio:
                          type: string
                          description: Municipality name. Resolved to IBGE code automatically
                        cod_municipio:
                          type: string
                          description: 7-digit IBGE municipality code
                        uf:
                          type: string
                          description: State abbreviation (2 chars)
                          example: SP
                        cep:
                          type: string
                          description: Postal code (CEP, 8 digits, no dashes)
                          example: 04571936
                        telefone:
                          type: string
                          description: Phone number with area code (6-14 chars)
                produtos:
                  type: array
                  description: List of declared products (min 1, max 999)
                  minItems: 1
                  maxItems: 999
                  items:
                    type: object
                    required:
                    - xProd
                    - NCM
                    - qCom
                    - vUnCom
                    - vProd
                    properties:
                      xProd:
                        type: string
                        description: Product description (1-120 chars). Avoid special characters like apostrophes
                        example: LIVRO DE RECEITAS
                      NCM:
                        type: string
                        description: NCM code (Nomenclatura Comum do Mercosul). 2 digits for chapter or 8 digits for full code, no dots. SEFAZ validates against MDIC table. If you don't know the NCM code, you can use the [Classify HS code](https://docs.envia.com/reference/classify-hs-code) endpoint to look it up from a product description
                      qCom:
                        type: string
                        description: Product quantity (up to 11 integer digits, 0-4 decimal places)
                      vUnCom:
                        type: string
                        description: Unit price (up to 11 integer digits, 0-4 decimal places). Use dot as decimal separator
                      vProd:
                        type: string
                        description: Total product value (qCom x vUnCom). Exactly 2 decimal places. Max per item R$100,000. Total DC-e max R$200,000
                transp:
                  type: object
                  description: Transport information
                  required:
                  - carrierName
                  properties:
                    carrierName:
                      type: string
                      description: Carrier name as registered in the envia.com catalog. Case-insensitive lookup
                      example: buslog
                infAdic:
                  type: string
                  description: Additional information for the DC-e (1-5000 chars)
                  example: BENS DE USO PESSOAL SEM VALOR COMERCIAL
            examples:
              Generate DC-e:
                summary: Generate a DC-e for non-commercial shipment
                value:
                  ide:
                    uf: SP
                  emit:
                    CNPJ: '40432544000147'
                    xNome: JOAO DA SILVA
                    endereco:
                      logradouro: Rua Henri Dunant
                      numero: '780'
                      bairro: Santo Amaro
                      municipio: SAO PAULO
                      uf: SP
                      cep: '01310100'
                  dest:
                    CPF: 06782783932
                    xNome: MARIA OLIVEIRA
                    endereco:
                      logradouro: Avenida Engenheiro Luiz Carlos Berrini
                      numero: '1376'
                      bairro: Cidade Monções
                      municipio: SAO PAULO
                      uf: SP
                      cep: 04571936
                  produtos:
                  - xProd: LIVRO DE RECEITAS
                    NCM: '49019900'
                    qCom: '2'
                    vUnCom: '25.00'
                    vProd: '50.00'
                  - xProd: ROUPA USADA
                    NCM: '62'
                    qCom: '5'
                    vUnCom: '10.00'
                    vProd: '50.00'
                  transp:
                    carrierName: buslog
                  infAdic: BENS DE USO PESSOAL SEM VALOR COMERCIAL
      responses:
        '200':
          description: Successful DC-e authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the authorization was successful
                  cStat:
                    type: string
                    description: Status code returned by SEFAZ. 100 = Authorization approved
                    example: '100'
                  xMotivo:
                    type: string
                    description: Human-readable description of the authorization result
                    example: Autorizado o uso do DCe
                  documentType:
                    type: string
                    description: Type of the returned document
                    example: dce
                  dceNumber:
                    type: string
                    description: Generated DC-e number
                    example: '374'
                  dceSerie:
                    type: string
                    description: DC-e series number
                    example: '1'
                  dceDate:
                    type: string
                    format: date-time
                    description: DC-e emission date and time
                    example: '2026-04-06T20:37:41-03:00'
                  dceKey:
                    type: string
                    description: 44-digit DC-e access key
                    example: '35260440728044000157990010000003741101480600'
                  dceValue:
                    type: string
                    description: Total value of the DC-e document
                    example: '100.00'
                  nProt:
                    type: string
                    description: Authorization protocol number from SEFAZ
                    example: '3352600000044170'
                  dhRecbto:
                    type: string
                    format: date-time
                    description: Date and time when SEFAZ received and processed the authorization
                    example: '2026-04-06T20:37:42-03:00'
                  xml:
                    type: string
                    description: Complete signed XML of the authorized DC-e document. Shown abbreviated in documentation for readability
              examples:
                Success:
                  summary: Successful DC-e authorization
                  value:
                    success: true
                    cStat: '100'
                    xMotivo: Autorizado o uso do DCe
                    documentType: dce
                    dceNumber: '374'
                    dceSerie: '1'
                    dceDate: '2026-04-06T20:37:41-03:00'
                    dceKey: '35260440728044000157990010000003741101480600'
                    dceValue: '100.00'
                    nProt: '3352600000044170'
                    dhRecbto: '2026-04-06T20:37:42-03:00'
                    xml: <DCe xmlns='http://www.portalfiscal.inf.br/dce'>...signed XML content...</DCe>
  /dce/cancelar:
    post:
      tags:
      - DC-e
      summary: Cancel a DC-e
      description: 'Cancel an existing DC-e (Declaração de Conteúdo Eletrônica) in the Brazilian fiscal system. The DC-e must have been previously authorized.


        **When to use:** Call this endpoint when you need to cancel a previously issued DC-e — for example, if the shipment was cancelled or the declaration was issued in error.


        **Prerequisites:**

        - Valid JWT authentication token (Bearer)

        - The 44-digit DC-e access key (`dceKey`) from the original DC-e authorization


        **Key behaviors:**

        - Returns the cancellation status from SEFAZ (Brazilian tax authority)

        - The `cStat` field indicates the result: `135` means cancellation was approved

        - Once cancelled, the DC-e cannot be reused

        - The `nProt` field contains the cancellation protocol number for record-keeping'
      operationId: cancel-dce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - dceKey
              properties:
                dceKey:
                  type: string
                  description: The 44-digit DC-e access key from the original authorization
                  example: '35260440728044000157990010000003741101480600'
            example:
              dceKey: '35260440728044000157990010000003741101480600'
      responses:
        '200':
          description: Successful DC-e cancellation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the cancellation request was successful
                  tpAmb:
                    type: string
                    description: 'Environment type: 1 = Production, 2 = Homologation (testing)'
                    example: '2'
                  verAplic:
                    type: string
                    description: Version of the SEFAZ application that processed the request
                    example: PR-v0.13.0
                  cOrgao:
                    type: string
                    description: IBGE code of the issuing state
                    example: '35'
                  cStat:
                    type: string
                    description: Status code from SEFAZ. 135 = Cancellation approved
                    example: '135'
                  xMotivo:
                    type: string
                    description: Human-readable reason for the status
                    example: Cancelamento homologado
                  chDCe:
                    type: string
                    description: The 44-digit DC-e access key that was cancelled
                    example: '35260440728044000157990010000003741101480600'
                  tpEvento:
                    type: string
                    description: Event type code. 110111 = Cancellation
                    example: '110111'
                  xEvento:
                    type: string
                    description: Event name
                    example: Cancelamento
                  nSeqEvento:
                    type: string
                    description: Sequence number of the event
                    example: '1'
                  dhRegEvento:
                    type: string
                    format: date-time
                    description: Date and time when the event was registered at SEFAZ
                    example: '2026-04-06T20:42:03-03:00'
                  nProt:
                    type: string
                    description: Protocol number of the cancellation for record-keeping
                    example: '3352600000044171'
              examples:
                Success:
                  summary: Successful DC-e cancellation
                  value:
                    success: true
                    tpAmb: '2'
                    verAplic: PR-v0.13.0
                    cOrgao: '35'
                    cStat: '135'
                    xMotivo: Cancelamento homologado
                    chDCe: '35260440728044000157990010000003741101480600'
                    tpEvento: '110111'
                    xEvento: Cancelamento
                    nSeqEvento: '1'
                    dhRegEvento: '2026-04-06T20:42:03-03:00'
                    nProt: '3352600000044171'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  description: Full Envia API Documentation
  url: https://docs.envia.com
x-provenance:
  method: searched
  source: https://docs.envia.com/reference
  harvested: '2026-10-27'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.envia.com/reference/active-notifications.md
  - https://docs.envia.com/reference/additional-services-by-locale.md
  - https://docs.envia.com/reference/additional-services.md
  - https://docs.envia.com/reference/addresses-by-type.md
  - https://docs.envia.com/reference/all-addresses.md
  - https://docs.envia.com/reference/all-countries.md
  - https://docs.envia.com/reference/all-packages.md
  - https://docs.envia.com/reference/all-provinces.md
  - https://docs.envia.com/reference/all-webhooks.md
  - https://docs.envia.com/reference/available-carriers-by-shipment-type.md
  - https://docs.envia.com/reference/available-couriers-detailed.md
  - https://docs.envia.com/reference/available-services.md
  - https://docs.envia.com/reference/cancel-dce.md
  - https://docs.envia.com/reference/carrier-actions-by-carrier.md
  - https://docs.envia.com/reference/carrier-branches.md
  - https://docs.envia.com/reference/carrier-by-id.md
  - https://docs.envia.com/reference/carrier-print-options.md
  - https://docs.envia.com/reference/carriers-by-country.md
  - https://docs.envia.com/reference/country-address-structure.md
  - https://docs.envia.com/reference/country-by-code.md
  - https://docs.envia.com/reference/country-locale.md
  - https://docs.envia.com/reference/create-ndr-request.md
  - https://docs.envia.com/reference/create-package.md
  - https://docs.envia.com/reference/create-shop-shipping-rule.md
  - https://docs.envia.com/reference/create-user-address.md
  - https://docs.envia.com/reference/create-webhook.md
  - https://docs.envia.com/reference/deactivate-company-notifications.md
  - https://docs.envia.com/reference/default-shop-services.md
  - https://docs.envia.com/reference/default-user-address.md
  - https://docs.envia.com/reference/default-user-print.md
  - https://docs.envia.com/reference/download-labels-bulk.md
  - https://docs.envia.com/reference/estafeta-branches-mexico.md
  - https://docs.envia.com/reference/generate-dce.md
  - https://docs.envia.com/reference/get-orders.md
  - https://docs.envia.com/reference/invoice-detail.md
  - https://docs.envia.com/reference/ndr-history.md
  - https://docs.envia.com/reference/ndr-shipment-actions.md
  - https://docs.envia.com/reference/payment-history.md
  - https://docs.envia.com/reference/province-by-code.md
  - https://docs.envia.com/reference/remove-package.md
  - https://docs.envia.com/reference/remove-user-address.md
  - https://docs.envia.com/reference/select-shipping-rule-for-order.md
  - https://docs.envia.com/reference/serviceable-countries.md
  - https://docs.envia.com/reference/services-by-carrier-and-country.md
  - https://docs.envia.com/reference/services-by-carrier.md
  - https://docs.envia.com/reference/shipment-by-tracking.md
  - https://docs.envia.com/reference/shipment-types.md
  - https://docs.envia.com/reference/shipments-by-month-year.md
  - https://docs.envia.com/reference/shop-by-url.md
  - https://docs.envia.com/reference/shop-shipping-rule.md
  - https://docs.envia.com/reference/shop-shipping-rules.md
  - https://docs.envia.com/reference/state-by-code.md
  - https://docs.envia.com/reference/states-by-country.md
  - https://docs.envia.com/reference/update-package.md
  - https://docs.envia.com/reference/update-shop-shipping-rules.md
  - https://docs.envia.com/reference/update-user-address.md
  - https://docs.envia.com/reference/update-webhook.md
  - https://docs.envia.com/reference/webhook-types.md
  merge:
    pages: 58
    deduped: 57
    conflicts_kept_first: 0