Customer Account NS

Endpoints da WebApiAlcance para gerenciar as contas contábeis do cliente no NS Sistemas (Nota Salvador) - o vínculo entre um cliente da Alcance e suas credenciais de acesso ao portal da Nota Salvador. Cobrem registro de uma nova conta, listagem geral, detalhamento por ID, atualização parcial e exclusão.

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/customer-account-ns

Escopos necessários

customer_account_ns:read - listagem e detalhamento
customer_account_ns:write - registro, atualização e exclusão

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

Endpoints

`POST /customer-account-ns/`

Registra uma nova conta da Nota Salvador vinculada a um cliente. Em caso de sucesso retorna 200 OK (e não 201 Created).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (CustomerAccountNsCreate): cliente_id (obrigatório), login (obrigatório), acesso_padrao (opcional, default true) e senha (opcional).

Request

{
  "cliente_id": 1234,
  "login": "12345678000199",
  "senha": "s3nh4-secreta",
  "acesso_padrao": true
}

Response 200 OK

{
  "success": true,
  "message": "Conta registrada com sucesso!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "login": "12345678000199",
    "acesso_padrao": true
  }
}

Quando o registro não é possível, retorna o envelope de erro com success: false e message: "Nao foi possivel registrar a conta.". Escopo: customer_account_ns:write

`GET /customer-account-ns/{account_id}`

Detalha uma conta pelo ID inteiro. Quando não encontrada, retorna 404 Not Found com detail: "Conta não encontrada.".

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Conta encontrada!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "login": "12345678000199",
    "acesso_padrao": true
  }
}

Escopo: customer_account_ns:read

`GET /customer-account-ns/`

Lista todas as contas cadastradas. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contas listadas com sucesso!",
  "data": [
    { "id": 42, "cliente_id": 1234, "login": "12345678000199", "acesso_padrao": true },
    { "id": 43, "cliente_id": 5678, "login": "98765432000188", "acesso_padrao": false }
  ]
}

Escopo: customer_account_ns:read

`PUT /customer-account-ns/{account_id}`

Atualiza uma conta existente. O body é um CustomerAccountNsUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

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

Request (CustomerAccountNsUpdate - todos os campos opcionais)

{
  "login": "12345678000199",
  "acesso_padrao": false
}

Response 200 OK

{
  "success": true,
  "message": "Conta atualizada com sucesso!",
  "data": {
    "id": 42,
    "cliente_id": 1234,
    "login": "12345678000199",
    "acesso_padrao": false
  }
}

Escopo: customer_account_ns:write

`DELETE /customer-account-ns/{account_id}`

Remove uma conta pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Conta removida com sucesso!",
  "data": null
}

Escopo: customer_account_ns:write

Schemas

`CustomerAccountNsCreate`

Campo	Tipo	Obrigatório	Observações
`cliente_id`	`int`	sim	ID do cliente ao qual a conta pertence.
`login`	`str`	sim	Login de acesso ao portal da Nota Salvador.
`acesso_padrao`	`bool`	não	Indica a conta padrão de acesso. Default `true`.
`senha`	`str`	não	Senha de acesso. Campo de escrita apenas - nunca é retornado.

`CustomerAccountNsUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`login`	`str`	Novo login de acesso.
`senha`	`str`	Nova senha (campo de escrita apenas).
`acesso_padrao`	`bool`	Redefine se é a conta padrão de acesso.

`CustomerAccountNsRead`

Campo	Tipo	Notas
`id`	`int`	Identificador da conta.
`cliente_id`	`int`	Cliente vinculado à conta.
`login`	`str`	Login de acesso ao portal.
`acesso_padrao`	`bool`	Se é a conta padrão de acesso.

Credencial nunca é exposta

O campo senha vive apenas nos schemas de escrita (CustomerAccountNsCreate / CustomerAccountNsUpdate) e fica fora do CustomerAccountNsRead. Isso evita que a senha vaze em texto plano nas respostas de GET /{account_id} e GET / (issue #525).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O POST /customer-account-ns/ retorna 200 OK (e não 201 Created) em caso de sucesso.
GET /customer-account-ns/{account_id} é declarado antes da rota de listagem GET /customer-account-ns/, ambas com paths distintos - não há conflito de roteamento.