{
 "openapi": "3.0.3",
 "info": {
  "title": "Contta — API de NFS-e Nacional",
  "version": "1.0.0",
  "description": "\nAPI de NFS-e Nacional do Contta: emite, consulta, cancela e devolve o PDF de notas de serviço pelo\nemissor nacional (Sefin Nacional), em nome das empresas do seu escritório.\n\n**Como funciona.** Você manda o FATO (o que foi feito, para quem e quanto). O Contta decide código\nde serviço, alíquota, retenção e regime pelo cadastro fiscal da empresa e devolve uma PRÉVIA. A nota\nsó sai quando você confirma a prévia com o `previa_hash`. Faltou algo: a resposta traz `pendencias`\ncom a pergunta pronta; pedido recusado traz `proximo_passo`.\n\n**Autenticação.** `Authorization: Bearer ctk_...`. A chave é criada por um responsável do escritório\n(owner/admin) em Contta > Emissão > Chaves de API e age em nome dessa pessoa. Escopos:\n`nfse:emitir` (emitir, confirmar, cancelar) e `nfse:consultar` (consultar, listar, PDF, XML).\n\n**Teste e produção.** Chave nova emite só na homologação nacional (nota de teste, sem valor fiscal).\nNota real exige chave liberada pelo dono do escritório e a empresa liberada para produção.\n\n**Idempotência.** Mande `request_id` no corpo ou o header `Idempotency-Key`: o mesmo pedido repetido\ndevolve o mesmo resultado, sem nota em dobro. Resposta 202 no confirmar = o fisco ainda não respondeu:\nconsulte, nunca confirme de novo.\n\n**Limite.** 120 pedidos por minuto por chave (HTTP 429 acima disso).\n"
 },
 "paths": {
  "/api/v1/nfse-nacional/": {
   "get": {
    "operationId": "listar_nfse",
    "summary": "Listar pedidos",
    "parameters": [
     {
      "in": "query",
      "name": "empresa_id",
      "schema": {
       "type": "string"
      },
      "description": "Empresa; sem ela, use all_empresas=true."
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ListaNfse"
        }
       }
      },
      "description": ""
     }
    }
   },
   "post": {
    "operationId": "emitir_nfse",
    "description": "Monta a prévia da nota a partir do FATO (o que, para quem, quanto). Imposto, código e alíquota o sistema decide; não se mandam. Faltou algo: estado REJECTED com `pendencias`. Chave sem liberação de produção: a nota vai para a homologação nacional (teste).",
    "summary": "Emitir (montar a prévia)",
    "tags": [
     "NFS-e Nacional"
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/EmitirNfseRequest"
       },
       "examples": {
        "NotaDeServiço": {
         "value": {
          "empresa_id": "3f0c6c2e-0000-4000-8000-000000000001",
          "request_id": "venda-2026-11-08-0001",
          "fato": {
           "descricao": "Consultoria contábil de novembro",
           "valor": "1500.00",
           "tomador": {
            "documento": "11222333000181"
           }
          }
         },
         "summary": "Nota de serviço"
        }
       }
      }
     },
     "required": true
    },
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "201": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PedidoNfse"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/{comando_id}/": {
   "get": {
    "operationId": "consultar_nfse",
    "summary": "Consultar um pedido",
    "parameters": [
     {
      "in": "path",
      "name": "comando_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PedidoNfse"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/{comando_id}/cancelar/": {
   "post": {
    "operationId": "cancelar_nfse",
    "description": "Devolve o pedido de cancelamento com prévia; confirme em /{id}/confirmar/ do NOVO pedido.",
    "summary": "Cancelar (montar o pedido)",
    "parameters": [
     {
      "in": "path",
      "name": "comando_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CancelarNfseRequest"
       }
      }
     },
     "required": true
    },
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "201": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PedidoNfse"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/{comando_id}/confirmar/": {
   "post": {
    "operationId": "confirmar_nfse",
    "description": "Envia ao fisco a prévia conferida. 202 = o fisco ainda não respondeu: consulte de novo, nunca confirme outra vez.",
    "summary": "Confirmar (emitir de fato)",
    "parameters": [
     {
      "in": "path",
      "name": "comando_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/ConfirmarNfseRequest"
       }
      }
     },
     "required": true
    },
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PedidoNfse"
        }
       }
      },
      "description": ""
     },
     "202": {
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PedidoNfse"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/{comando_id}/pdf/": {
   "get": {
    "operationId": "pdf_nfse",
    "summary": "PDF da nota (DANFSe)",
    "parameters": [
     {
      "in": "path",
      "name": "comando_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "content": {
       "application/pdf": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/{comando_id}/xml/": {
   "get": {
    "operationId": "xml_nfse",
    "summary": "XML autorizado",
    "parameters": [
     {
      "in": "path",
      "name": "comando_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "NFS-e Nacional"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "content": {
       "application/xml": {
        "schema": {
         "type": "string",
         "format": "binary"
        }
       }
      },
      "description": ""
     }
    }
   }
  },
  "/api/v1/nfse-nacional/chaves/": {
   "get": {
    "operationId": "listar_chaves_api",
    "summary": "Listar chaves",
    "tags": [
     "Chaves de API"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "description": "No response body"
     }
    }
   },
   "post": {
    "operationId": "criar_chave_api",
    "description": "O texto da chave volta UMA vez, na criação. Guarde-o: depois só aparece o prefixo.",
    "summary": "Criar chave",
    "tags": [
     "Chaves de API"
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/CriarChaveRequest"
       }
      }
     },
     "required": true
    },
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "description": "No response body"
     }
    }
   }
  },
  "/api/v1/nfse-nacional/chaves/{chave_id}/revogar/": {
   "post": {
    "operationId": "revogar_chave_api",
    "summary": "Revogar chave",
    "parameters": [
     {
      "in": "path",
      "name": "chave_id",
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "required": true
     }
    ],
    "tags": [
     "Chaves de API"
    ],
    "security": [
     {
      "chave": []
     },
     {}
    ],
    "responses": {
     "200": {
      "description": "No response body"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "AmbienteEsperadoEnum": {
    "enum": [
     "HOMOLOGATION",
     "PRODUCTION"
    ],
    "type": "string",
    "description": "* `HOMOLOGATION` - HOMOLOGATION\n* `PRODUCTION` - PRODUCTION"
   },
   "CancelarNfseRequest": {
    "type": "object",
    "properties": {
     "justificativa": {
      "type": "string",
      "minLength": 1,
      "description": "De 15 a 255 letras."
     },
     "codigo_motivo": {
      "type": "string",
      "minLength": 1,
      "description": "1 = erro na emissão (padrão)."
     }
    },
    "required": [
     "justificativa"
    ]
   },
   "ConfirmarNfseRequest": {
    "type": "object",
    "properties": {
     "previa_hash": {
      "type": "string",
      "minLength": 1
     },
     "ambiente_esperado": {
      "allOf": [
       {
        "$ref": "#/components/schemas/AmbienteEsperadoEnum"
       }
      ],
      "description": "Ambiente que você viu na prévia. Sem ele, vale o da própria prévia.\n\n* `HOMOLOGATION` - HOMOLOGATION\n* `PRODUCTION` - PRODUCTION"
     }
    },
    "required": [
     "previa_hash"
    ]
   },
   "CriarChaveRequest": {
    "type": "object",
    "properties": {
     "nome": {
      "type": "string",
      "minLength": 1
     },
     "escopos": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/EscoposEnum"
      }
     },
     "producao": {
      "type": "boolean",
      "description": "Só o dono do escritório libera nota real."
     }
    },
    "required": [
     "escopos",
     "nome"
    ]
   },
   "EmitirNfseRequest": {
    "type": "object",
    "properties": {
     "fato": {
      "$ref": "#/components/schemas/FatoNfseRequest"
     },
     "empresa_id": {
      "type": "string",
      "format": "uuid"
     },
     "request_id": {
      "type": "string",
      "minLength": 1,
      "description": "Chave de idempotência do pedido. Sem ela vale o header Idempotency-Key."
     }
    },
    "required": [
     "empresa_id",
     "fato"
    ]
   },
   "EscoposEnum": {
    "enum": [
     "nfse:emitir",
     "nfse:consultar"
    ],
    "type": "string",
    "description": "* `nfse:emitir` - nfse:emitir\n* `nfse:consultar` - nfse:consultar"
   },
   "FatoNfseRequest": {
    "type": "object",
    "properties": {
     "descricao": {
      "type": "string",
      "minLength": 1,
      "description": "O que foi feito, como deve sair na nota."
     },
     "valor": {
      "type": "string",
      "minLength": 1,
      "description": "Valor total do serviço, em reais (ex.: \"1500.00\")."
     },
     "data_fato": {
      "type": "string",
      "format": "date",
      "description": "Data do serviço; sem ela, hoje."
     },
     "tomador": {
      "$ref": "#/components/schemas/TomadorNfseRequest"
     },
     "servico_slug": {
      "type": "string",
      "minLength": 1,
      "description": "Serviço cadastrado da empresa (a resposta oferece as opções quando há mais de um)."
     }
    },
    "required": [
     "descricao",
     "valor"
    ]
   },
   "ListaNfse": {
    "type": "object",
    "properties": {
     "itens": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": {}
      }
     }
    },
    "required": [
     "itens"
    ]
   },
   "PedidoNfse": {
    "type": "object",
    "properties": {
     "comando_id": {
      "type": "string",
      "format": "uuid"
     },
     "estado": {
      "type": "string"
     },
     "ambiente": {
      "type": "string",
      "description": "HOMOLOGATION (teste) ou PRODUCTION (real)."
     },
     "previa": {
      "type": "object",
      "additionalProperties": {},
      "description": "Prévia; `hash` vai no confirmar."
     },
     "pendencias": {
      "type": "array",
      "items": {
       "type": "object",
       "additionalProperties": {}
      },
      "description": "O que falta, com a pergunta pronta."
     },
     "proximo_passo": {
      "type": "object",
      "additionalProperties": {},
      "description": "Pedido recusado: o que fazer."
     },
     "numero": {
      "type": "string",
      "nullable": true
     },
     "chave": {
      "type": "string",
      "nullable": true
     },
     "mensagem_leiga": {
      "type": "string"
     }
    },
    "required": [
     "ambiente",
     "chave",
     "comando_id",
     "estado",
     "mensagem_leiga",
     "numero",
     "pendencias",
     "previa"
    ]
   },
   "TomadorNfseRequest": {
    "type": "object",
    "properties": {
     "documento": {
      "type": "string",
      "minLength": 1,
      "description": "CPF ou CNPJ de quem contratou."
     },
     "nome": {
      "type": "string",
      "minLength": 1
     }
    },
    "required": [
     "documento"
    ]
   }
  },
  "securitySchemes": {
   "chave": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "ctk_...",
    "description": "Chave de API do escritório (Contta > Emissão > Chaves de API)."
   }
  }
 },
 "servers": [
  {
   "url": "https://app.contta.com.br",
   "description": "Produção (chave sem liberação = homologação)"
  }
 ],
 "tags": [
  {
   "name": "NFS-e Nacional"
  },
  {
   "name": "Chaves de API",
   "description": "Só pela tela, com login."
  }
 ],
 "externalDocs": {
  "description": "Referência com exemplos",
  "url": "https://contta.com.br/dev/api"
 }
}
