Customer Config Integrações

Endpoints da WebApiAlcance para as configurações de integração externa de cada cliente. Cada configuração é identificada pela combinação (id_cliente, sistema, ambiente) e guarda a chave de acesso (api_key), a data de validade e o status da integração.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.

A api_key é write-only

A api_key entra apenas na criação e na atualização. Nenhuma resposta a devolve. Na leitura você recebe configurado, api_key_mascarada (somente os 4 últimos caracteres) e mascara_indisponivel.

Base path

/api/v1/customer-config-integracoes

Escopos necessários

  • customer_config_integracoes:read - listagem global, consulta por cliente e consulta por ID (rotas GET).
  • customer_config_integracoes:write - criação, atualização e remoção (POST, PUT, DELETE).

O escopo é derivado do prefixo público da rota: /customer-config-integracoes vira o recurso customer_config_integracoes (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/PATCH/DELETE).

Além do escopo, as rotas POST, PUT, DELETE e a listagem global GET / exigem permissão adicional; sem ela, a resposta é 403. As consultas pontuais (/by-customer/{customer_id} e /{config_id}) exigem apenas o escopo.

Envelope de resposta

Toda resposta segue o envelope padrão da WebApi:

{
  "status": "success",
  "message": "Mensagem em PT-BR",
  "data": {}
}

Erros de negócio retornam { "message": ... } com o status HTTP correspondente. Falhas de validação retornam 422 com { "detail": [...] }.

Endpoints

POST /customer-config-integracoes/

Cria a configuração de integração de um cliente. Responde 201 Created.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo (ver CustomerConfigIntegracoesCreate).

Request

{
  "id_cliente": 123,
  "sistema": "serpro",
  "ambiente": "producao",
  "api_key": "sk_live_xxxxxxxxxxxx",
  "data_validade": "2026-12-31",
  "status": "ativo"
}

Response 201 Created

{
  "status": "success",
  "message": "Configuração de integração criada com sucesso!",
  "data": {
    "id": 15,
    "id_cliente": 123,
    "id_usuario_created": 7,
    "sistema": "serpro",
    "ambiente": "producao",
    "data_validade": "2026-12-31",
    "status": "ativo",
    "configurado": true,
    "api_key_mascarada": "••••xxxx",
    "mascara_indisponivel": false,
    "expirada": false,
    "created_at": "2026-08-05T09:12:44-03:00",
    "updated_at": "2026-08-05T09:12:44-03:00"
  }
}

Erros: 404 quando o cliente não existe; 409 quando já existe configuração para o mesmo cliente, sistema e ambiente; 422 para payload inválido.

Normalização

sistema e ambiente são normalizados (sem espaços nas pontas, minúsculas). " Serpro " e "serpro" são o mesmo sistema e colidem no 409.

Escopo: customer_config_integracoes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /customer-config-integracoes/

Lista as configurações de integração de todos os clientes. Acesso restrito a usuários com permissão adicional.

Parâmetros de query

ParâmetroTipoObrigatórioObservações
pageint (≥ 1)nãoPágina, 1-based. Deve ser enviado junto com per_page.
per_pageint (1-500)nãoItens por página. Deve ser enviado junto com page.

Enviar apenas um dos dois retorna 422. Sem ambos, a listagem não é paginada.

Request

GET /api/v1/customer-config-integracoes/?page=1&per_page=50

Response 200 OK

{
  "status": "success",
  "message": "Configurações de integração recuperadas com sucesso!",
  "data": [
    {
      "id": 15,
      "id_cliente": 123,
      "id_usuario_created": 7,
      "sistema": "serpro",
      "ambiente": "producao",
      "data_validade": "2026-12-31",
      "status": "ativo",
      "configurado": true,
      "api_key_mascarada": "••••xxxx",
      "mascara_indisponivel": false,
      "expirada": false,
      "created_at": "2026-08-05T09:12:44-03:00",
      "updated_at": "2026-08-05T09:12:44-03:00"
    }
  ]
}

data é uma lista de CustomerConfigIntegracoesRead. Sem registros, retorna data: [] com a mensagem "Nenhuma configuração de integração encontrada.".

Listagem sem paginação é limitada a 500

Sem page e per_page, a resposta é truncada em 500 registros. Quando há corte, a message indica PARCIAL. Use page e per_page para percorrer o restante.

Escopo: customer_config_integracoes:read. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

GET /customer-config-integracoes/by-customer/{customer_id}

Lista as configurações de integração de um cliente.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
customer_idrotaintsimID do cliente.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Configurações de integração encontradas!",
  "data": [
    {
      "id": 15,
      "id_cliente": 123,
      "id_usuario_created": 7,
      "sistema": "serpro",
      "ambiente": "producao",
      "data_validade": "2026-12-31",
      "status": "ativo",
      "configurado": true,
      "api_key_mascarada": "••••xxxx",
      "mascara_indisponivel": false,
      "expirada": false,
      "created_at": "2026-08-05T09:12:44-03:00",
      "updated_at": "2026-08-05T09:12:44-03:00"
    }
  ]
}

Lista vazia não é erro: retorna 200 com data: [] e a mensagem "Nenhuma configuração de integração para este cliente.".

Escopo: customer_config_integracoes:read

GET /customer-config-integracoes/{config_id}

Consulta uma configuração pelo ID.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
config_idrotaintsimID da configuração.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Configuração de integração encontrada!",
  "data": {
    "id": 15,
    "id_cliente": 123,
    "id_usuario_created": 7,
    "sistema": "serpro",
    "ambiente": "producao",
    "data_validade": "2026-12-31",
    "status": "ativo",
    "configurado": true,
    "api_key_mascarada": "••••xxxx",
    "mascara_indisponivel": false,
    "expirada": false,
    "created_at": "2026-08-05T09:12:44-03:00",
    "updated_at": "2026-08-05T09:12:44-03:00"
  }
}

ID inexistente retorna 404 Not Found.

Escopo: customer_config_integracoes:read

PUT /customer-config-integracoes/{config_id}

Atualiza api_key, data_validade e status de uma configuração. id_cliente, sistema e ambiente são imutáveis.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
config_idrotaintsimID da configuração.

Request

{
  "api_key": "sk_live_novaChave123",
  "data_validade": "2027-01-31",
  "status": "ativo"
}

Todos os campos são opcionais (ver CustomerConfigIntegracoesUpdate). Omitir api_key mantém a chave atual.

Response 200 OK

{
  "status": "success",
  "message": "Configuração de integração atualizada!",
  "data": {
    "id": 15,
    "id_cliente": 123,
    "id_usuario_created": 7,
    "sistema": "serpro",
    "ambiente": "producao",
    "data_validade": "2027-01-31",
    "status": "ativo",
    "configurado": true,
    "api_key_mascarada": "••••e123",
    "mascara_indisponivel": false,
    "expirada": false,
    "created_at": "2026-08-05T09:12:44-03:00",
    "updated_at": "2026-09-01T14:30:00-03:00"
  }
}

ID inexistente retorna 404 Not Found.

Escopo: customer_config_integracoes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

DELETE /customer-config-integracoes/{config_id}

Remove uma configuração pelo ID.

Parâmetros

ParâmetroLocalTipoObrigatórioObservações
config_idrotaintsimID da configuração.

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Configuração de integração removida!",
  "data": null
}

ID inexistente retorna 404 Not Found.

Escopo: customer_config_integracoes:write. Restrita a usuários com permissão adicional; sem ela, a resposta é 403.

Schemas

CustomerConfigIntegracoesCreate

Corpo de POST /customer-config-integracoes/.

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente dono da configuração.
sistemastr (1-50)simSistema externo (texto livre). Normalizado: sem espaços nas pontas, minúsculas.
ambiente"producao" | "homologacao"nãoDefault producao. Normalizado como sistema.
api_keystr (8-4096) | nullnãoChave da integração. Write-only. Espaços nas pontas são removidos antes da validação de tamanho.
data_validadedate | nullnãoAAAA-MM-DD. Data no passado é aceita.
status"ativo" | "inativo" | "revogado"nãoDefault ativo.

CustomerConfigIntegracoesUpdate

Corpo de PUT /customer-config-integracoes/{config_id}. Todos os campos são opcionais.

CampoTipoObservações
api_keystr (8-4096) | nullNova chave. Write-only. Omitir mantém a atual.
data_validadedate | nullNova validade. Data no passado é aceita.
status"ativo" | "inativo" | "revogado"Novo status.

CustomerConfigIntegracoesRead

Item de data em todas as respostas de leitura.

CampoTipoObservações
idintID da configuração.
id_clienteintID do cliente.
id_usuario_createdintUsuário que criou a configuração.
sistemastrSistema externo, normalizado.
ambiente"producao" | "homologacao"Ambiente da credencial.
data_validadedate | nullValidade da credencial.
status"ativo" | "inativo" | "revogado"Status da configuração.
configuradobooltrue quando há chave salva.
api_key_mascaradastr | nullSomente os 4 últimos caracteres, precedidos de ••••. null sem chave ou quando indisponível.
mascara_indisponivelbooltrue quando há chave salva mas a máscara não pôde ser produzida; exige contato com o suporte.
expiradabooltrue quando data_validade existe e já passou (fuso de São Paulo).
created_atdatetimeCriação.
updated_atdatetimeÚltima atualização.

Notas

  • A chave de uma configuração é (id_cliente, sistema, ambiente); duplicar a combinação retorna 409.
  • api_key nunca é devolvida. Para confirmar qual chave está salva, compare os 4 últimos caracteres em api_key_mascarada.
  • No PUT, omitir api_key preserva a chave atual; enviar um valor a substitui.
  • expirada é calculada na leitura e não altera o status.