Avalara Electronic Invoices API

openapi: 3.1.0
info:
  title: Avalara AvaTax Brazil Electronic Invoices API
  description: The AvaTax Brazil API provides tax calculation, electronic invoice (NF-e, NFS-e, NFC-e) issuance, and transaction management for businesses with a physical presence in Brazil. It supports Brazilian federal, state, and municipal taxes including ICMS, IPI, PIS, COFINS, ISS, and more.
  version: '1.0'
  contact:
    name: Avalara Developer Relations
    url: https://developer.avalara.com/
    email: developer.relations@avalara.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://legal.avalara.com/#siteterms
servers:
- url: https://avataxbr-sandbox.avalarabrasil.com.br/v3
  description: AvaTax Brazil Sandbox
security:
- bearerAuth: []
tags:
- name: Electronic Invoices
  description: Issue and manage electronic fiscal documents
paths:
  /invoices:
    post:
      operationId: createInvoice
      summary: Avalara Issue an Electronic Invoice
      description: Issues a new electronic fiscal document (NF-e, NFS-e, or NFC-e) to Brazilian tax authorities (SEFAZ).
      tags:
      - Electronic Invoices
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceRequest'
      responses:
        '201':
          description: Invoice issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
    get:
      operationId: listInvoices
      summary: Avalara List Electronic Invoices
      tags:
      - Electronic Invoices
      parameters:
      - name: startDate
        in: query
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        schema:
          type: string
          format: date
      - name: status
        in: query
        schema:
          type: string
          enum:
          - Authorized
          - Cancelled
          - Denied
          - Pending
      - name: page
        in: query
        schema:
          type: integer
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: List of invoices
  /invoices/{invoiceId}:
    get:
      operationId: getInvoice
      summary: Avalara Get an Invoice by ID
      tags:
      - Electronic Invoices
      parameters:
      - name: invoiceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Invoice details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponse'
  /invoices/{invoiceId}/cancel:
    post:
      operationId: cancelInvoice
      summary: Avalara Cancel an Electronic Invoice
      description: Submits a cancellation request for an authorized invoice.
      tags:
      - Electronic Invoices
      parameters:
      - name: invoiceId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Cancellation reason
      responses:
        '200':
          description: Invoice cancelled
components:
  schemas:
    BrazilParty:
      type: object
      properties:
        name:
          type: string
        cnpj:
          type: string
          description: Company tax ID (CNPJ)
        cpf:
          type: string
          description: Individual tax ID (CPF)
        stateRegistration:
          type: string
          description: Inscricao Estadual
        municipalRegistration:
          type: string
          description: Inscricao Municipal
        address:
          type: object
          properties:
            street:
              type: string
            number:
              type: string
            complement:
              type: string
            neighborhood:
              type: string
            city:
              type: string
            cityCode:
              type: string
              description: IBGE city code
            state:
              type: string
              description: State code (UF)
            postalCode:
              type: string
            country:
              type: string
    InvoiceLine:
      type: object
      properties:
        lineNumber:
          type: integer
        itemCode:
          type: string
        description:
          type: string
        quantity:
          type: number
          format: double
        unitPrice:
          type: number
          format: double
        ncmCode:
          type: string
        cfopCode:
          type: string
    InvoiceResponse:
      type: object
      properties:
        invoiceId:
          type: string
        accessKey:
          type: string
          description: 44-digit NF-e access key
        invoiceNumber:
          type: integer
        series:
          type: integer
        status:
          type: string
          enum:
          - Authorized
          - Cancelled
          - Denied
          - Pending
        protocolNumber:
          type: string
        issuanceDate:
          type: string
          format: date-time
    InvoiceRequest:
      type: object
      properties:
        invoiceType:
          type: string
          enum:
          - NF-e
          - NFS-e
          - NFC-e
          - CT-e
          description: Electronic document type
        companyId:
          type: string
        transactionDate:
          type: string
          format: date-time
        buyer:
          $ref: '#/components/schemas/BrazilParty'
        lines:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLine'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication
externalDocs:
  description: AvaTax Brazil API Documentation
  url: https://developer.avalara.com/api-reference/avatax-brazil/v1/