openapi: 3.0.0
info:
  description: Endpoints openapi responsável pelo contexto de notas fiscais
  title: Notas fiscais
  contact: {}
  version: v1
paths:
  /v1/notas-fiscais:
    get:
      security:
        - BearerAuth: []
      tags:
        - v1
      summary: Retornar as notas fiscais por filtro
      operationId: obterNotasFiscaisPorFiltro
      parameters:
        - description: Data inicial no formato YYYY-MM-DD
          name: data_inicial
          in: query
          required: true
          schema:
            type: string
        - description: Data final no formato YYYY-MM-DD
          name: data_final
          in: query
          required: true
          schema:
            type: string
        - description: Página
          name: pagina
          in: query
          schema:
            type: integer
            default: 1
        - description: Tamanho da página
          name: tamanho_pagina
          in: query
          schema:
            type: integer
            default: 10
        - description: Documento do tomador
          name: documento_tomador
          in: query
          schema:
            type: string
        - description: Número da nota fiscal
          name: numero_nota
          in: query
          schema:
            type: string
        - description: ID da venda
          name: id_venda
          in: query
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotaFiscalPorFiltro'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
  /v1/notas-fiscais/vinculo-mdfe:
    post:
      security:
        - BearerAuth: []
      tags:
        - v1
      summary: Vincular nota fiscal a mdfe
      operationId: vincularNotaFiscalMdfe
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkNotaFiscalMdfe'
        description: Dados para vincular nota fiscal a mdfe
        required: true
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroAPI'
  /v1/notas-fiscais/{chave}:
    get:
      security:
        - BearerAuth: []
      tags:
        - v1
      summary: Retornar a nota fiscal por chave
      operationId: obterNotaFiscalPorChave
      parameters:
        - description: Chave da nota fiscal
          name: chave
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/xml:
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '404':
          description: Not Found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErroAPI'
        '500':
          description: Internal Server Error
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErroAPI'
tags:
  - description: Operações relacionadas a notas fiscais
    name: v1
servers:
  - url: https://api-v2.contaazul.com
components:
  securitySchemes:
    BearerAuth:
      description: >-
        Digite **'Bearer &lt;JWT&gt;'**, onde JWT é o access_token recebido no
        login (passo 2 do fluxo de autenticação).
      type: apiKey
      name: Authorization
      in: header
  schemas:
    ErroAPI:
      description: Modelo de resposta para erros da API
      type: object
      properties:
        error:
          description: Mensagem de erro
          type: string
          example: Mensagem de erro detalhada
    LinkNotaFiscalMdfe:
      description: Modelo de link de chaves de notas fiscais para MDF-e
      type: object
      required:
        - chaves_acesso
        - identificador
      properties:
        chaves_acesso:
          description: Chaves de acesso das notas fiscais vinculadas ao MDF-e
          type: array
          items:
            type: string
          example:
            - '42250323643586000108550010000001151606401726'
            - '42250323643586000108550010000001141054498495'
        identificador:
          description: Identificador do MDF-e
          type: string
          example: '345345'
        status:
          description: Status do MDF-e
          allOf:
            - $ref: '#/components/schemas/StatusDoMDFE'
          example: ENCERRADO
    NotaFiscal:
      description: >-
        Modelo de resposta para as notas fiscais contendo todas as informações
        necessárias
      type: object
      properties:
        chave_acesso:
          description: Chave de acesso da nota fiscal
          type: string
          example: '42250323643586000108550010000001151606401726'
        data_emissao:
          description: Data de emissão da nota fiscal
          type: string
          example: '2025-01-15T10:30:00Z'
        nome_destinatario:
          description: Nome do destinatário
          type: string
          example: EMPRESA EXEMPLO LTDA
        numero_nota:
          description: Número da nota fiscal
          type: integer
          example: 123456
        status:
          description: Status da nota fiscal
          allOf:
            - $ref: '#/components/schemas/StatusDaNotaFiscal'
          example: EMITIDA
    NotaFiscalPorFiltro:
      description: >-
        Modelo de resposta para as notas fiscais contendo todas as informações
        necessárias
      type: object
      properties:
        itens:
          description: Lista de notas fiscais
          type: array
          items:
            $ref: '#/components/schemas/NotaFiscal'
        paginacao:
          description: Paginação
          allOf:
            - $ref: '#/components/schemas/Pagina_o'
    StatusDaNotaFiscal:
      description: Enum de status da nota fiscal
      type: string
      enum:
        - EMITIDA
        - CORRIGIDA_SUCESSO
      x-enum-varnames:
        - EMITTED
        - SUCCESS_CORRECTION
    StatusDoMDFE:
      description: Enum de status do MDF-e (Manifesto Eletrônico de Documentos Fiscais)
      type: string
      enum:
        - AUTORIZADO
        - ENCERRADO
        - CANCELADO
      x-enum-varnames:
        - AUTHORIZED
        - CLOSED
        - CANCELED
    Pagina_o:
      description: Modelo de resposta para paginação dos resultados
      type: object
      properties:
        pagina_atual:
          description: Página atual
          type: integer
          example: 1
        tamanho_pagina:
          description: Tamanho da página
          type: integer
          example: 10
        total_itens:
          description: Total de itens
          type: integer
          example: 50
        total_paginas:
          description: Total de páginas
          type: integer
          example: 5
