{
  "openapi": "3.1.0",
  "info": {
    "title": "Foou · API de produção",
    "version": "0.1.0",
    "description": "Portal administrativo e do cliente, acesso por certificado, consultas fiscais, arquivos e recebimento de webhooks. O acesso por certificado requer configuração do serviço mTLS dedicado e confiança ICP-Brasil, conforme o guia de implantação."
  },
  "servers": [
    {
      "url": "https://api.foou.com.br",
      "description": "Produção · HTTPS ativo"
    }
  ],
  "paths": {
    "/api/admin/login": {
      "post": {
        "operationId": "login",
        "summary": "Entrar no portal",
        "tags": [
          "Autenticação"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "csrf": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 200
                  },
                  "password": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  }
                },
                "required": [
                  "email",
                  "password"
                ]
              },
              "example": {
                "email": "admin@example.invalid",
                "password": ""
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/session": {
      "get": {
        "operationId": "session",
        "summary": "Consultar sessão",
        "tags": [
          "Autenticação"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "csrf": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/logout": {
      "post": {
        "operationId": "logout",
        "summary": "Encerrar sessão",
        "tags": [
          "Autenticação"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Concluído sem conteúdo"
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients": {
      "get": {
        "operationId": "listClients",
        "summary": "Listar clientes",
        "tags": [
          "Administração"
        ],
        "description": "Lista até 500 clientes, ordenados por criação. Paginação ainda não implementada.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "provisioning",
                              "active",
                              "failed"
                            ]
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "status",
                          "createdAt"
                        ]
                      }
                    },
                    "limit": {
                      "type": "integer"
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "post": {
        "operationId": "createClient",
        "summary": "Cadastrar cliente",
        "tags": [
          "Administração"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "provisioning",
                        "active",
                        "failed"
                      ]
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "status",
                    "createdAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 160
                  }
                },
                "required": [
                  "name"
                ]
              },
              "example": {
                "name": "Cliente Demonstração"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies": {
      "get": {
        "operationId": "listCompanies",
        "summary": "Listar CNPJs",
        "tags": [
          "Administração"
        ],
        "description": "Lista até 500 CNPJs do cliente, ordenados pelo nome. Paginação ainda não implementada.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "cnpj": {
                            "type": "string",
                            "pattern": "^[0-9]{14}$"
                          },
                          "root": {
                            "type": "string",
                            "pattern": "^[0-9]{8}$"
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "cnpj",
                          "root"
                        ]
                      }
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "post": {
        "operationId": "createCompany",
        "summary": "Cadastrar CNPJ",
        "tags": [
          "Administração"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "name": {
                      "type": "string"
                    },
                    "cnpj": {
                      "type": "string",
                      "pattern": "^[0-9]{14}$"
                    },
                    "root": {
                      "type": "string",
                      "pattern": "^[0-9]{8}$"
                    }
                  },
                  "required": [
                    "id",
                    "name",
                    "cnpj",
                    "root"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 160
                  },
                  "cnpj": {
                    "type": "string",
                    "description": "CNPJ numérico válido ou com pontuação; o backend normaliza e valida os dígitos verificadores."
                  }
                },
                "required": [
                  "name",
                  "cnpj"
                ]
              },
              "example": {
                "name": "Empresa Demonstração",
                "cnpj": "12345678000195"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/provision": {
      "post": {
        "operationId": "provision",
        "summary": "Solicitar provisionamento",
        "tags": [
          "Administração"
        ],
        "description": "Registra um job durável. Um worker separado cria banco e usuário exclusivo, aplica o schema e valida a conexão. Chamadas repetidas não duplicam o banco. Falhas podem ser reenfileiradas. Cadastre ao menos um CNPJ antes.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Solicitação registrada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "get": {
        "operationId": "provisionStatus",
        "summary": "Consultar provisionamento",
        "tags": [
          "Administração"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "provisioning",
                        "active",
                        "failed"
                      ]
                    },
                    "job": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "running",
                            "done",
                            "failed"
                          ]
                        },
                        "attempts": {
                          "type": "integer"
                        },
                        "error_code": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  },
                  "required": []
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/integration": {
      "get": {
        "operationId": "integrationStatus",
        "summary": "Consultar configuração Focus",
        "tags": [
          "Administração"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokenConfigured": {
                      "type": "boolean"
                    },
                    "webhookTokenConfigured": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "tokenConfigured",
                    "webhookTokenConfigured"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "put": {
        "operationId": "saveIntegration",
        "summary": "Configurar tokens Focus",
        "tags": [
          "Administração"
        ],
        "description": "Token da API por filial. Compatibilidade: webhookToken ainda altera SOMENTE o segredo anterior daquela filial; novos cadastros devem usar PUT /api/admin/clients/{clientId}/webhook. Campos vazios preservam. Nunca retorna segredos.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tokenConfigured": {
                      "type": "boolean"
                    },
                    "webhookTokenConfigured": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "tokenConfigured",
                    "webhookTokenConfigured"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "maxLength": 8192,
                    "description": "Vazio ou ausente preserva o valor atual."
                  },
                  "webhookToken": {
                    "type": "string",
                    "maxLength": 8192,
                    "description": "Mínimo de 32 caracteres quando informado; vazio preserva.",
                    "deprecated": true
                  }
                },
                "required": [],
                "additionalProperties": false
              },
              "example": {
                "token": "",
                "webhookToken": ""
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/integration/{kind}": {
      "delete": {
        "operationId": "removeToken",
        "summary": "Remover token explicitamente",
        "tags": [
          "Administração"
        ],
        "description": "Operação administrativa restrita aos administradores da plataforma Foou.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "focus",
                "webhook"
              ]
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Concluído sem conteúdo"
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/webhooks/focus/nfce": {
      "post": {
        "operationId": "nfceWebhook",
        "summary": "Receber notificação NFC-e",
        "tags": [
          "Integração NFC-e"
        ],
        "description": "Contrato de recebimento do Foou em produção. Persiste a notificação no banco do cliente antes de responder 200. Payloads idênticos são deduplicados; atualizações de status são preservadas. Retorna 200 em repetição. Não baixa XML, não emite NFC-e, não atualiza situação fiscal e não registra automaticamente o webhook na Focus. Os detalhes de entrega e retentativas do provedor ainda precisam ser confirmados na documentação atual da Focus. Campos adicionais são preservados. Não enviar credenciais no corpo. O CNPJ identifica a filial e seu cliente. Aceita o segredo compartilhado do cliente ou, durante a transição, apenas o segredo anterior daquela filial. Nunca aceita segredo de outro cliente.",
        "security": [
          {
            "webhookBearer": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recebido": {
                      "const": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "recebido"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "503": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "cnpj_emitente": {
                    "type": "string",
                    "pattern": "^\\d{14}$"
                  },
                  "ref": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "status": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "status_sefaz": {
                    "type": "string"
                  },
                  "mensagem_sefaz": {
                    "type": "string"
                  },
                  "chave_nfe": {
                    "type": "string"
                  },
                  "numero": {
                    "type": "string"
                  },
                  "serie": {
                    "type": "string"
                  },
                  "caminho_xml_nota_fiscal": {
                    "type": "string"
                  },
                  "caminho_danfe": {
                    "type": "string"
                  },
                  "qrcode_url": {
                    "type": "string"
                  },
                  "url_consulta_nf": {
                    "type": "string"
                  },
                  "contingencia_offline": {
                    "type": "boolean"
                  },
                  "contingencia_offline_efetivada": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "cnpj_emitente",
                  "ref",
                  "status"
                ],
                "additionalProperties": {}
              },
              "example": {
                "cnpj_emitente": "12345678000195",
                "ref": "nfce-producao-001",
                "status": "autorizado",
                "status_sefaz": "100",
                "mensagem_sefaz": "Autorizado o uso da NF-e",
                "numero": "1",
                "serie": "1",
                "caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfce.xml",
                "caminho_danfe": "/arquivos/exemplo/danfe.html"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://api.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfce": {
      "get": {
        "operationId": "listNotifications",
        "summary": "Listar notificações NFC-e",
        "tags": [
          "Administração"
        ],
        "description": "Consulta administrativa somente de leitura. Lista até 50 notificações da empresa, da mais recente para a mais antiga. total informa a quantidade persistida. Não retorna payload completo, credenciais ou URLs de documentos. state é o estado de processamento no Foou; status é o valor informado pela Focus. O recebimento não representa importação do XML nem validação fiscal.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "received",
                              "processing",
                              "processed",
                              "failed"
                            ]
                          },
                          "receivedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ref": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "numero": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "serie": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "statusSefaz": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "hasXml": {
                            "type": "boolean"
                          },
                          "attempts": {
                            "type": "integer"
                          },
                          "lastErrorCode": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "document": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "amount": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "customer": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "parsed": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "required": [
                          "id",
                          "state",
                          "receivedAt",
                          "ref",
                          "status",
                          "numero",
                          "serie",
                          "statusSefaz",
                          "hasXml"
                        ]
                      }
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "limit": {
                      "type": "integer",
                      "const": 50
                    }
                  },
                  "required": [
                    "items",
                    "total",
                    "limit"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/webhooks/focus/nfe": {
      "post": {
        "operationId": "nfeWebhook",
        "summary": "Receber notificação NF-e",
        "tags": [
          "Integração NF-e"
        ],
        "description": "Contrato de recebimento de NF-e do Foou em produção. Autentica pelo segredo de webhook já configurado para a empresa, separado do token Focus. Persiste a notificação no banco exclusivo do cliente antes de responder 200. Repetições idênticas são deduplicadas em tabela própria de NF-e, separada de NFC-e. Mudanças de status geram novas notificações. Não emite NF-e, não baixa XML nem atualiza a situação fiscal; 200 confirma somente recebimento durável. Configuração e entrega real do evento Focus ainda precisam ser validadas. O CNPJ identifica a filial e seu cliente. Aceita o segredo compartilhado do cliente ou, durante a transição, apenas o segredo anterior daquela filial. Nunca aceita segredo de outro cliente.",
        "security": [
          {
            "webhookBearer": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recebido": {
                      "const": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "recebido"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "503": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "cnpj_emitente": {
                    "type": "string",
                    "pattern": "^\\d{14}$"
                  },
                  "ref": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "status": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "status_sefaz": {
                    "type": "string"
                  },
                  "mensagem_sefaz": {
                    "type": "string"
                  },
                  "chave_nfe": {
                    "type": "string"
                  },
                  "numero": {
                    "type": "string"
                  },
                  "serie": {
                    "type": "string"
                  },
                  "caminho_xml_nota_fiscal": {
                    "type": "string"
                  },
                  "caminho_danfe": {
                    "type": "string"
                  },
                  "protocolo": {
                    "type": "string",
                    "description": "Protocolo preservado como texto, quando fornecido."
                  }
                },
                "required": [
                  "cnpj_emitente",
                  "ref",
                  "status"
                ],
                "additionalProperties": {}
              },
              "example": {
                "cnpj_emitente": "12345678000195",
                "ref": "nfe-producao-001",
                "status": "autorizado",
                "status_sefaz": "100",
                "mensagem_sefaz": "Autorizado o uso da NF-e",
                "chave_nfe": "NFe00000000000000000000000000000000000000000000",
                "numero": "1",
                "serie": "1",
                "protocolo": "000000000000000",
                "caminho_xml_nota_fiscal": "/arquivos/exemplo/nota-nfe.xml",
                "caminho_danfe": "/arquivos/exemplo/danfe.pdf"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://api.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfe": {
      "get": {
        "operationId": "listNfeNotifications",
        "summary": "Listar notificações NF-e",
        "tags": [
          "Administração"
        ],
        "description": "Consulta administrativa somente de leitura. Lista até 50 notificações NF-e da empresa, da mais recente para a mais antiga. total informa a quantidade persistida. Não retorna payload completo, credenciais ou URLs de documentos. state é o estado de processamento no Foou; status é o valor informado pela Focus. O recebimento não representa importação do XML nem validação fiscal. Consulta a tabela exclusiva de NF-e, sem misturar registros NFC-e.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "received",
                              "processing",
                              "processed",
                              "failed"
                            ]
                          },
                          "receivedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ref": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "numero": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "serie": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "statusSefaz": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "hasXml": {
                            "type": "boolean"
                          },
                          "attempts": {
                            "type": "integer"
                          },
                          "lastErrorCode": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "document": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "properties": {
                              "amount": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "customer": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "parsed": {
                                "type": "boolean"
                              }
                            }
                          }
                        },
                        "required": [
                          "id",
                          "state",
                          "receivedAt",
                          "ref",
                          "status",
                          "numero",
                          "serie",
                          "statusSefaz",
                          "hasXml"
                        ]
                      }
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "limit": {
                      "type": "integer",
                      "const": 50
                    }
                  },
                  "required": [
                    "items",
                    "total",
                    "limit"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/auth/start": {
      "post": {
        "operationId": "portalStart",
        "summary": "Iniciar acesso por certificado",
        "tags": [
          "Portal do cliente"
        ],
        "security": [],
        "parameters": [
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authorizeUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "required": [
                    "authorizeUrl"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Inicia o fluxo no navegador com e-CNPJ A1 ICP-Brasil. Gera tentativa de 5 minutos e cookie de estado HttpOnly. Retorna authorizeUrl do serviço mTLS dedicado. Se o serviço não estiver configurado, retorna 503; não existe login alternativo sem validação de certificado.",
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/auth/callback": {
      "get": {
        "operationId": "portalCallback",
        "summary": "Concluir acesso por certificado",
        "tags": [
          "Portal do cliente"
        ],
        "security": [],
        "parameters": [
          {
            "in": "query",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "in": "query",
            "name": "attempt",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Operação concluída"
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Callback automático do navegador após o serviço mTLS validar cadeia, revogação, validade e CNPJ. Exige cookie de estado e código de uso único de 60 segundos. Cria sessão e redireciona para /portal/. Não aceita certificado, CNPJ ou chave privada no corpo.",
        "x-foou-mutates-state": true,
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/session": {
      "get": {
        "operationId": "portalSession",
        "summary": "Consultar sessão do cliente",
        "tags": [
          "Portal do cliente"
        ],
        "security": [
          {
            "portalCookie": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cnpj": {
                      "type": "string"
                    },
                    "csrf": {
                      "type": "string"
                    },
                    "companies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          },
                          "cnpj": {
                            "type": "string"
                          },
                          "clientId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "clientName": {
                            "type": "string"
                          }
                        },
                        "required": []
                      }
                    }
                  },
                  "required": [
                    "cnpj",
                    "csrf",
                    "companies"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração.",
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/logout": {
      "post": {
        "operationId": "portalLogout",
        "summary": "Encerrar sessão do cliente",
        "tags": [
          "Portal do cliente"
        ],
        "security": [
          {
            "portalCookie": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Operação concluída"
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração.",
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/documents": {
      "get": {
        "operationId": "portalDocuments",
        "summary": "Listar notas fiscais",
        "tags": [
          "Portal do cliente"
        ],
        "security": [
          {
            "portalCookie": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "clientId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "companyId",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "in": "query",
            "name": "search",
            "schema": {
              "type": "string",
              "maxLength": 160
            }
          },
          {
            "in": "query",
            "name": "number",
            "schema": {
              "type": "string",
              "maxLength": 30
            }
          },
          {
            "in": "query",
            "name": "series",
            "schema": {
              "type": "string",
              "maxLength": 10
            }
          },
          {
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string",
              "enum": [
                "autorizado",
                "cancelado",
                "denegado",
                "erro_autorizacao",
                "processando_autorizacao"
              ]
            }
          },
          {
            "in": "query",
            "name": "model",
            "schema": {
              "type": "string",
              "enum": [
                "55",
                "65"
              ]
            }
          },
          {
            "in": "query",
            "name": "min",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}(\\.[0-9]{1,2})?$"
            }
          },
          {
            "in": "query",
            "name": "max",
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}(\\.[0-9]{1,2})?$"
            }
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "companyId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "model": {
                            "type": "string",
                            "enum": [
                              "55",
                              "65"
                            ]
                          },
                          "ref": {
                            "type": "string"
                          },
                          "accessKey": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "number": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "series": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "issuerCnpj": {
                            "type": "string"
                          },
                          "issuerName": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "customer": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "customerDocument": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "issuedAt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "format": "date-time"
                          },
                          "status": {
                            "type": "string"
                          },
                          "amount": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Valor decimal exato como texto, não centavos inteiros."
                          },
                          "parsed": {
                            "type": "boolean"
                          },
                          "hasXml": {
                            "type": "boolean"
                          },
                          "hasDanfe": {
                            "type": "boolean"
                          }
                        },
                        "required": []
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "totalValue": {
                      "type": "string"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "size": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "items",
                    "total",
                    "totalValue",
                    "page",
                    "size"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. Filtros e paginação são executados no servidor. Datas usam America/Sao_Paulo. Valor e cliente podem estar ausentes enquanto o XML está em processamento. clientId é necessário quando o certificado acessa mais de um cliente.",
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/documents/{documentId}/{kind}": {
      "get": {
        "operationId": "portalAsset",
        "summary": "Baixar XML ou abrir DANFE",
        "tags": [
          "Portal do cliente"
        ],
        "security": [
          {
            "portalCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "documentId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "xml",
                "danfe"
              ]
            }
          },
          {
            "in": "query",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. O backend busca o arquivo de origem sem expor token ou URL. XML é baixado; PDF abre inline; HTML é baixado como arquivo. Não há armazenamento permanente de XML/PDF.",
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/portal/downloads": {
      "post": {
        "operationId": "portalBatch",
        "summary": "Baixar documentos selecionados em ZIP",
        "tags": [
          "Portal do cliente"
        ],
        "security": [
          {
            "portalCookie": []
          }
        ],
        "parameters": [
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Parâmetros inválidos"
          },
          "401": {
            "description": "Sessão ausente ou expirada"
          },
          "403": {
            "description": "Origem/CSRF, cadastro ou permissão inválida"
          },
          "404": {
            "description": "Cadastro ou documento não encontrado"
          },
          "409": {
            "description": "Arquivo indisponível"
          },
          "413": {
            "description": "Tamanho excedido; selecionar menos documentos"
          },
          "429": {
            "description": "Limite atingido; tentar novamente"
          },
          "503": {
            "description": "Serviço ou arquivo temporariamente indisponível"
          }
        },
        "description": "Operação do portal restrita às filiais cadastradas com a mesma raiz do certificado e cadastradas em cliente ativo. Não retorna credenciais da integração. Até 25 notas e 50 MiB por lote; o conjunto inteiro é autorizado antes dos downloads. Arquivos originais são incluídos em ZIP, sem consolidação em PDF único. Uma preparação em lote por instância.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "xml",
                      "danfe"
                    ]
                  },
                  "ids": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 25
                  }
                },
                "required": [
                  "clientId",
                  "kind",
                  "ids"
                ]
              },
              "example": {
                "clientId": "00000000-0000-4000-8000-000000000001",
                "kind": "xml",
                "ids": [
                  "00000000-0000-4000-8000-000000000002"
                ]
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://app.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}": {
      "put": {
        "operationId": "updateCompany",
        "summary": "Editar empresa",
        "tags": [
          "Administração"
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "name": "clientId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "companyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 160
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cadastro atualizado"
          },
          "403": {
            "description": "Acesso negado"
          },
          "404": {
            "description": "Empresa não encontrada"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/webhook": {
      "get": {
        "operationId": "clientWebhookStatus",
        "summary": "Consultar webhook do cliente",
        "tags": [
          "Administração"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuração sem segredos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhookTokenConfigured",
                    "legacyCompanyCount"
                  ],
                  "properties": {
                    "webhookTokenConfigured": {
                      "type": "boolean"
                    },
                    "legacyCompanyCount": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Autenticação obrigatória"
          },
          "403": {
            "description": "Origem/CSRF inválidos"
          },
          "409": {
            "description": "Banco do cliente ainda não está ativo"
          }
        },
        "description": "Retorna somente indicadores. legacyCompanyCount conta segredos anteriores preservados para transição sem interromper entregas.",
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "put": {
        "operationId": "saveClientWebhook",
        "summary": "Configurar webhook do cliente",
        "tags": [
          "Administração"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Configuração sem segredos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhookTokenConfigured",
                    "legacyCompanyCount"
                  ],
                  "properties": {
                    "webhookTokenConfigured": {
                      "type": "boolean"
                    },
                    "legacyCompanyCount": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Autenticação obrigatória"
          },
          "403": {
            "description": "Origem/CSRF inválidos"
          },
          "409": {
            "description": "Banco do cliente ainda não está ativo"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "webhookToken": {
                    "type": "string",
                    "maxLength": 8192,
                    "writeOnly": true,
                    "description": "Mínimo 32 caracteres quando preenchido. Vazio preserva. Não é devolvido."
                  }
                }
              },
              "example": {
                "webhookToken": "{{webhookToken}}"
              }
            }
          }
        },
        "description": "Segredo compartilhado pelas filiais do cliente, criptografado exclusivamente em seu banco com AAD do cliente. Preserva os segredos antigos por filial até revogação explícita.",
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      },
      "delete": {
        "operationId": "removeClientWebhook",
        "summary": "Remover webhook do cliente",
        "tags": [
          "Administração"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "responses": {
          "204": {
            "description": "Removido"
          },
          "401": {
            "description": "Autenticação obrigatória"
          },
          "403": {
            "description": "Origem/CSRF inválidos"
          },
          "409": {
            "description": "Banco do cliente ainda não está ativo"
          }
        },
        "description": "Remove explicitamente o segredo do cliente E todos os segredos anteriores das suas filiais. Interrompe recebimento dos webhooks deste cliente. Preserva tokens da API, notas e demais clientes.",
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/webhook/legacy": {
      "delete": {
        "operationId": "retireLegacyWebhooks",
        "summary": "Revogar segredos anteriores das filiais",
        "tags": [
          "Administração"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "description": "Usar somente depois de atualizar todas as filiais para o segredo do cliente. Revoga apenas segredos antigos por filial; mantém o segredo do cliente e os tokens da API. Requer segredo do cliente configurado.",
        "responses": {
          "200": {
            "description": "Transição concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhookTokenConfigured",
                    "legacyCompanyCount"
                  ],
                  "properties": {
                    "webhookTokenConfigured": {
                      "type": "boolean"
                    },
                    "legacyCompanyCount": {
                      "type": "integer",
                      "minimum": 0
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Origem/CSRF inválidos"
          },
          "409": {
            "description": "Configure o segredo do cliente antes de revogar os antigos"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/webhooks": {
      "post": {
        "operationId": "registerCompanyWebhook",
        "summary": "Criar webhook da empresa",
        "tags": [
          "Administração"
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "header",
            "name": "X-CSRF-Token",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Origin",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "security": [
          {
            "adminCookie": []
          }
        ],
        "description": "Ação explícita por filial, apenas em produção. Requer token da API da filial e segredo do webhook do cliente salvos. Consulta GET /v2/hooks antes do POST para evitar duplicação, incluindo chamadas simultâneas e repetição após falha incerta. Reutiliza cadastro compatível existente; conflito de configuração retorna409 e não remove/substitui nenhum webhook. Não cria ao salvar token/segredo. Retorna apenas metadados públicos, nunca credenciais. Eventos disponíveis: nfe, nfse e nfce_consulta_automatica. NFS-e usa um endpoint próprio de recebimento; esta etapa registra notificações e não interpreta XML NFS-e nem inclui NFS-e na grade fiscal.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "event"
                ],
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": [
                      "nfe",
                      "nfse",
                      "nfce_consulta_automatica"
                    ]
                  }
                }
              },
              "example": {
                "event": "nfe"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook compatível já existe; não criou duplicado",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "event": {
                      "type": "string"
                    },
                    "cnpj": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "created": {
                      "type": "boolean"
                    },
                    "environment": {
                      "const": "producao"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Webhook criado em produção",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "event": {
                      "type": "string"
                    },
                    "cnpj": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "created": {
                      "type": "boolean"
                    },
                    "environment": {
                      "const": "producao"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Dados/evento inválidos"
          },
          "401": {
            "description": "Autenticação administrativa obrigatória"
          },
          "403": {
            "description": "Origem ou CSRF inválidos"
          },
          "404": {
            "description": "Empresa não pertence ao cliente"
          },
          "409": {
            "description": "Cadastre token e segredo, aguarde outra operação ou confira conflito existente"
          },
          "422": {
            "description": "Token recusado, sem permissão ou evento/dados rejeitados pela integração"
          },
          "502": {
            "description": "Operação não confirmada pela integração; próxima tentativa consulta antes de criar"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    },
    "/webhooks/focus/nfse": {
      "post": {
        "operationId": "nfseWebhook",
        "summary": "Receber notificação NFS-e",
        "tags": [
          "Integração NFS-e"
        ],
        "description": "Recebe e registra a notificação NFS-e no banco do cliente, com segredo do webhook, identificação do prestador e deduplicação. Requer cnpj_prestador ou cnpj_emitente; se ambos forem informados devem ser iguais. Preserva os campos adicionais. Não interpreta XML NFS-e nem gera documentos na grade NF-e/NFC-e nesta etapa.",
        "security": [
          {
            "webhookBearer": []
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "recebido": {
                      "const": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "recebido"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "503": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cnpj_prestador": {
                    "type": "string",
                    "pattern": "^\\d{14}$"
                  },
                  "cnpj_emitente": {
                    "type": "string",
                    "pattern": "^\\d{14}$"
                  },
                  "ref": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "status": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  }
                },
                "required": [
                  "ref",
                  "status"
                ],
                "anyOf": [
                  {
                    "required": [
                      "cnpj_prestador"
                    ]
                  },
                  {
                    "required": [
                      "cnpj_emitente"
                    ]
                  }
                ],
                "additionalProperties": true
              },
              "example": {
                "cnpj_prestador": "12345678000195",
                "ref": "nfse-producao-001",
                "status": "autorizado",
                "numero": "7"
              }
            }
          }
        },
        "servers": [
          {
            "url": "https://api.foou.com.br"
          }
        ]
      }
    },
    "/api/admin/clients/{clientId}/companies/{companyId}/notifications/nfse": {
      "get": {
        "operationId": "listNfseNotifications",
        "summary": "Listar notificações NFS-e",
        "tags": [
          "Administração"
        ],
        "description": "Consulta autenticada das últimas 50 notificações NFS-e da empresa, sem payload bruto ou segredos. Registro de recebimento; não representa interpretação do XML nem inclusão na grade fiscal.",
        "security": [
          {
            "adminCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "clientId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "companyId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operação concluída",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "state": {
                            "type": "string",
                            "const": "received"
                          },
                          "receivedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ref": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "status": {
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "numero": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "state",
                          "receivedAt",
                          "ref",
                          "status",
                          "numero"
                        ]
                      }
                    },
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "limit": {
                      "type": "integer",
                      "const": 50
                    }
                  },
                  "required": [
                    "items",
                    "total",
                    "limit"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "JSON ou campos inválidos"
          },
          "401": {
            "description": "Autenticação ausente, inválida ou expirada"
          },
          "403": {
            "description": "Origem/CSRF inválidos ou empresa sem integração"
          },
          "404": {
            "description": "Cliente ou empresa não encontrados"
          },
          "409": {
            "description": "Cadastro duplicado, cliente inativo ou pré-requisito ausente"
          },
          "413": {
            "description": "Payload excede 256 KiB"
          },
          "429": {
            "description": "Limite de requisições atingido"
          },
          "500": {
            "description": "Operação indisponível; resposta sem detalhes sensíveis"
          }
        },
        "servers": [
          {
            "url": "https://admin.foou.com.br"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "adminCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "foou_session",
        "description": "Sessão HttpOnly obtida no login; escritas exigem Origin e X-CSRF-Token."
      },
      "webhookBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Segredo de recebimento configurado para a empresa, separado do token da API Focus."
      },
      "portalCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "foou_portal_session",
        "description": "Sessão de até 1 hora emitida após mTLS e-CNPJ, vinculada ao CNPJ e limitada pela validade do certificado. Licenças e permissões são verificadas em toda chamada. Não é um token estático fornecido ao integrador."
      }
    }
  },
  "x-foou-deployment": {
    "verified": true,
    "environment": "producao",
    "verifiedAt": "2026-11-15T21:51:49.655382+00:00",
    "customDomainsReady": false
  }
}
