NFS-e/Repasse: Integrações

Endpoints da WebApiAlcance para configurar as integrações externas do produto NFS-e/Repasse (aplicação single-company webapp-nfs-repasse-medico). Uma integração guarda a credencial (api_key) usada para conectar o produto ao provider externo (atualmente apenas alcance). Cobrem criação, listagem, busca por provider, detalhamento por ID, atualização e exclusão.

Credencial write-only

A api_key é um dado sensível e write-only: entra no body de POST/PUT, mas nunca é retornada em leitura. O schema de leitura (IntegrationSettingRead) não possui o campo api_key - no lugar dele expõe configurado: bool e api_key_mascarada (apenas os 4 últimos caracteres, ex.: ••••f9a), para confirmar visualmente qual chave está ativa sem expor o segredo. Confirmado na fonte (schemas.py).

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/nfse-repasse/integracoes

Escopos necessários

Escopo compartilhado do produto NFS-e/Repasse

O 1º segmento da rota (nfse-repasse) define o recurso de escopo, que é compartilhado por todos os subdomínios do produto NFS-e/Repasse - não há um escopo integracoes próprio. Use:

nfse_repasse:read - listagem, busca por provider e detalhamento
nfse_repasse:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /nfse-repasse vira o recurso nfse_repasse (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /nfse-repasse/integracoes/`

Configura uma nova integração externa do produto NFS-e/Repasse. A api_key entra no corpo e é armazenada; a resposta de leitura devolve a chave sempre mascarada. Na fonte, a escrita exige perfil administrador.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (IntegrationSettingCreate): api_key (obrigatório, mín. 8 caracteres, write-only), provider (opcional, default "alcance"), descricao (opcional), ativo (opcional, default true) e uuid_legado (opcional).

Request

{
  "api_key": "sk_live_xxxxxxxxxxxx",
  "provider": "alcance",
  "descricao": "Chave de produção da API Alcance",
  "ativo": true
}

Response 201 Created

{
  "success": true,
  "message": "Integração configurada com sucesso!",
  "data": {
    "id": 1,
    "uuid_legado": null,
    "provider": "alcance",
    "descricao": "Chave de produção da API Alcance",
    "ativo": true,
    "configurado": true,
    "api_key_mascarada": "••••f9a",
    "last_tested_at": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Já existe integração para o provider retorna 409 Conflict; provider fora da allowlist ou api_key curta demais retorna 422 Unprocessable Entity. Escopo: nfse_repasse:write

`GET /nfse-repasse/integracoes/by-provider/{provider}`

Busca a integração de um provider específico. Declarada antes da rota dinâmica /{integracao_id} para não ser interpretada como um ID. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`provider`	`str`	path	sim	Provider da integração (ex.: `alcance`)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Integração encontrada!",
  "data": {
    "id": 1,
    "uuid_legado": null,
    "provider": "alcance",
    "descricao": "Chave de produção da API Alcance",
    "ativo": true,
    "configurado": true,
    "api_key_mascarada": "••••f9a",
    "last_tested_at": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/integracoes/`

Lista todas as integrações configuradas. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz um array de IntegrationSettingRead (sem api_key).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Integrações recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "uuid_legado": null,
      "provider": "alcance",
      "descricao": "Chave de produção da API Alcance",
      "ativo": true,
      "configurado": true,
      "api_key_mascarada": "••••f9a",
      "last_tested_at": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-03T12:00:00Z",
      "updated_at": "2026-07-03T12:00:00Z"
    }
  ]
}

Escopo: nfse_repasse:read

`GET /nfse-repasse/integracoes/{integracao_id}`

Detalha uma integração pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`integracao_id`	`int`	path	sim	ID interno da integração

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Integração encontrada!",
  "data": {
    "id": 1,
    "uuid_legado": null,
    "provider": "alcance",
    "descricao": "Chave de produção da API Alcance",
    "ativo": true,
    "configurado": true,
    "api_key_mascarada": "••••f9a",
    "last_tested_at": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T12:00:00Z"
  }
}

Escopo: nfse_repasse:read

`PUT /nfse-repasse/integracoes/{integracao_id}`

Atualiza uma integração existente. O corpo é um IntegrationSettingUpdate com campos parciais - somente o que vier preenchido é alterado. A api_key é opcional: omiti-la mantém a chave atual. provider e uuid_legado são imutáveis. Na fonte, a escrita exige perfil administrador.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`integracao_id`	`int`	path	sim	ID da integração

Request (IntegrationSettingUpdate - todos os campos opcionais)

{
  "descricao": "Chave de homologação da API Alcance",
  "ativo": false
}

Response 200 OK

{
  "success": true,
  "message": "Integração atualizada!",
  "data": {
    "id": 1,
    "uuid_legado": null,
    "provider": "alcance",
    "descricao": "Chave de homologação da API Alcance",
    "ativo": false,
    "configurado": true,
    "api_key_mascarada": "••••f9a",
    "last_tested_at": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-03T12:00:00Z",
    "updated_at": "2026-07-03T13:20:00Z"
  }
}

Escopo: nfse_repasse:write

`DELETE /nfse-repasse/integracoes/{integracao_id}`

Remove uma integração pelo ID. Na fonte, a escrita exige perfil administrador.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`integracao_id`	`int`	path	sim	ID da integração

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Integração removida!",
  "data": null
}

Escopo: nfse_repasse:write

Schemas

`IntegrationSettingCreate`

Payload de criação. A api_key entra aqui (write-only), mas nunca sai em leitura.

Campo	Tipo	Obrigatório	Observações
`api_key`	`str`	sim	Chave de API da integração. Mín. 8 caracteres. WRITE-ONLY - nunca retornada.
`provider`	`str`	não	Provider da integração. Allowlist: apenas `alcance`. Default `"alcance"`. Máx. 50.
`descricao`	`str`	não	Descrição/observação da integração.
`ativo`	`bool`	não	Se a integração está ativa. Default `true`.
`uuid_legado`	`str`	não	UUID do registro original no Supabase (rastreabilidade da migração). Máx. 36. Imutável depois.

id_usuario_created não entra no Create - é forçado pelo service a partir do usuário autenticado.

`IntegrationSettingUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados. provider, uuid_legado, id_usuario_created e timestamps são imutáveis aqui.

Campo	Tipo	Observações
`api_key`	`str`	Nova chave (WRITE-ONLY, mín. 8). Omitir = mantém a atual.
`descricao`	`str`	Nova descrição.
`ativo`	`bool`	Nova situação (ativa/inativa).
`last_tested_at`	`datetime`	Marca quando a chave foi testada por último.

`IntegrationSettingRead`

Schema de leitura. Não contém api_key - montado explicitamente pelo service (via from_entity) para garantir que o segredo jamais seja serializado.

Campo	Tipo	Notas
`id`	`int`	ID interno da integração.
`uuid_legado`	`str?`	UUID de origem (migração), ou `null`.
`provider`	`str`	Provider (ex.: `alcance`).
`descricao`	`str?`	Descrição, ou `null`.
`ativo`	`bool`	Se a integração está ativa.
`configurado`	`bool`	Se há uma chave de API salva.
`api_key_mascarada`	`str?`	Chave mascarada - só os 4 últimos caracteres (ex.: `••••f9a`), ou `null`.
`last_tested_at`	`datetime?`	Último teste da chave, ou `null`.
`id_usuario_created`	`int?`	ID do usuário que configurou (auditoria).
`created_at`	`datetime`	Criação do registro.
`updated_at`	`datetime`	Última atualização.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro). Códigos HTTP refletem semântica REST padrão.
Segurança: a api_key nunca aparece nas respostas. A leitura expõe apenas configurado e api_key_mascarada. A chave crua também não é registrada em log - apenas o provider. Confirmado na fonte (routes.py / schemas.py).
Armadilha de roteamento FastAPI. GET /by-provider/{provider} é declarada antes da rota dinâmica GET /{integracao_id}, para que /by-provider/... seja resolvida como rota estática (e não interpretada como um integracao_id).
Allowlist de provider: somente alcance é aceito (espelha o CHECK da origem). Providers fora da lista resultam em 422.
Origem: migração single-company do app webapp-nfs-repasse-medico (Supabase). Na fonte, escrita (POST/PUT/DELETE) exige perfil administrador e leitura exige staff autenticado; no gateway de API, o controle é feito pelos escopos nfse_repasse:read / nfse_repasse:write.