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-integracoesEscopos necessários
customer_config_integracoes:read- listagem global, consulta por cliente e consulta por ID (rotasGET).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âmetro | Tipo | Obrigatório | Observações |
|---|---|---|---|
page | int (≥ 1) | não | Página, 1-based. Deve ser enviado junto com per_page. |
per_page | int (1-500) | não | Itens 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=50Response 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
customer_id | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
config_id | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
config_id | rota | int | sim | ID 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âmetro | Local | Tipo | Obrigatório | Observações |
|---|---|---|---|---|
config_id | rota | int | sim | ID 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/.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | ID do cliente dono da configuração. |
sistema | str (1-50) | sim | Sistema externo (texto livre). Normalizado: sem espaços nas pontas, minúsculas. |
ambiente | "producao" | "homologacao" | não | Default producao. Normalizado como sistema. |
api_key | str (8-4096) | null | não | Chave da integração. Write-only. Espaços nas pontas são removidos antes da validação de tamanho. |
data_validade | date | null | não | AAAA-MM-DD. Data no passado é aceita. |
status | "ativo" | "inativo" | "revogado" | não | Default ativo. |
CustomerConfigIntegracoesUpdate
Corpo de PUT /customer-config-integracoes/{config_id}. Todos os campos são opcionais.
| Campo | Tipo | Observações |
|---|---|---|
api_key | str (8-4096) | null | Nova chave. Write-only. Omitir mantém a atual. |
data_validade | date | null | Nova validade. Data no passado é aceita. |
status | "ativo" | "inativo" | "revogado" | Novo status. |
CustomerConfigIntegracoesRead
Item de data em todas as respostas de leitura.
| Campo | Tipo | Observações |
|---|---|---|
id | int | ID da configuração. |
id_cliente | int | ID do cliente. |
id_usuario_created | int | Usuário que criou a configuração. |
sistema | str | Sistema externo, normalizado. |
ambiente | "producao" | "homologacao" | Ambiente da credencial. |
data_validade | date | null | Validade da credencial. |
status | "ativo" | "inativo" | "revogado" | Status da configuração. |
configurado | bool | true quando há chave salva. |
api_key_mascarada | str | null | Somente os 4 últimos caracteres, precedidos de ••••. null sem chave ou quando indisponível. |
mascara_indisponivel | bool | true quando há chave salva mas a máscara não pôde ser produzida; exige contato com o suporte. |
expirada | bool | true quando data_validade existe e já passou (fuso de São Paulo). |
created_at | datetime | Criação. |
updated_at | datetime | Última atualização. |
Notas
- A chave de uma configuração é
(id_cliente, sistema, ambiente); duplicar a combinação retorna409. api_keynunca é devolvida. Para confirmar qual chave está salva, compare os 4 últimos caracteres emapi_key_mascarada.- No
PUT, omitirapi_keypreserva a chave atual; enviar um valor a substitui. expiradaé calculada na leitura e não altera ostatus.