Guia de integração — Configurações CRM

Introdução

Este guia descreve a integração com a API unificada crm-config, que expõe operações CRUD sobre três tabelas de configuração CRM:

Valor (configType)	Nome
0	Categorias
1	Estados
2	Prioridades

Cada entrada é um registo simples com id (inteiro, atribuído na criação) e name (descrição textual). O mesmo contrato JSON aplica-se aos três tipos; apenas o segmento {configType} na rota determina qual tabela é acedida.

O endpoint suporta listagens paginadas e operações CRUD completas para integradores externos.

---

Valores aceites em {configType}

O parâmetro de rota configType identifica a tabela de configuração. São aceites, entre outros:

Formato	Exemplos	Notas
Numérico (recomendado)	0, 1, 2	Formato preferido para integração.
Slug descritivo	category-table, state, priority	Alternativa legível na URL.

Recomendação: usar 0, 1 ou 2 nas chamadas HTTP.

---

Endpoints disponíveis

Prefixo público: /gateway/crm-config/{configType}.

Método	URL	Descrição resumida
GET	/gateway/crm-config/{configType}	Lista entradas com paginação opcional (page, pageSize).
GET	/gateway/crm-config/{configType}/{id}	Obtém uma entrada por identificador.
POST	/gateway/crm-config/{configType}	Cria uma entrada; resposta 201 Created com o registo criado.
PUT	/gateway/crm-config/{configType}	Actualiza uma entrada existente; resposta 204 No Content.
DELETE	/gateway/crm-config/{configType}/{id}	Elimina por id; resposta 204 No Content.

Listar entradas

URL: /gateway/crm-config/{configType} — Método: GET

Parâmetros de consulta (opcionais):

Parâmetro	Tipo	Descrição
page	int	Número da página (base 1). Se omitido, usa-se página 1.
pageSize	int	Registos por página. Se omitido, usa-se 20; o máximo é 100.

Resposta (200 OK): corpo paginado — ver Estrutura da listagem paginada.

Ver mais →

Obter por identificador

URL: /gateway/crm-config/{configType}/{id} — Método: GET

Parâmetro de rota: id (int) — identificador da entrada.

Resposta (200 OK): objecto com id e name.

Ver mais →

Criar entrada

URL: /gateway/crm-config/{configType} — Método: POST

Corpo: JSON com a propriedade name.

Resposta (201 Created): corpo com o registo criado (id preenchido pelo servidor).

Ver mais →

Actualizar entrada

URL: /gateway/crm-config/{configType} — Método: PUT

Corpo: JSON com id e name.

Resposta (204 No Content) em sucesso.

Ver mais →

Eliminar entrada

URL: /gateway/crm-config/{configType}/{id} — Método: DELETE

Resposta (204 No Content) em sucesso.

Ver mais →

---

Estrutura da listagem paginada

A resposta de GET /gateway/crm-config/{configType} inclui metadados de paginação e a coleção de registos:

Campo	Tipo	Descrição
totalCount	int	Total de registos na tabela (todas as páginas).
pageSize	int	Tamanho efectivo da página devolvida.
currentPage	int	Página actual (base 1).
totalPages	int	Total de páginas.
data	array	Entradas da página pedida.

Cada elemento de data:

Campo	Tipo	Descrição
id	int	Identificador da entrada.
name	string	Descrição.

Exemplo de resposta (GET)

{
  "totalCount": 1,
  "pageSize": 50,
  "currentPage": 1,
  "totalPages": 1,
  "data": [
    {
      "id": 1,
      "name": "movo"
    }
  ]
}

Para percorrer todas as entradas, incremente page até currentPage atingir totalPages, ou pare quando data estiver vazio.

---

Estrutura do corpo do pedido

Criação (POST)

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Descrição da entrada.

Actualização (PUT)

Campo	Tipo	Obrigatório	Descrição
id	int	Sim	Identificador existente.
name	string	Sim	Nova descrição.

Limites de name por tipo

configType	Comprimento máximo de name
0 (Categorias)	4000 caracteres
1 (Estados)	40 caracteres
2 (Prioridades)	40 caracteres

Exceder o limite devolve o erro CrmConfig.NameMaxLengthExceeded.

---

Exemplos de pedidos

Listar categorias (primeira página, 50 registos)

GET /gateway/crm-config/0?page=1&pageSize=50

Equivalente com slug:

GET /gateway/crm-config/category-table?page=1&pageSize=50

Criar estado

POST /gateway/crm-config/1
Content-Type: application/json

{
  "name": "Em curso"
}

Actualizar prioridade

PUT /gateway/crm-config/2
Content-Type: application/json

{
  "id": 3,
  "name": "Alta"
}

Eliminar categoria

DELETE /gateway/crm-config/0/12

---

Erros frequentes

Código	Tipo HTTP típico	Significado e acção sugerida
CrmConfig.InvalidConfigType	400	{configType} inválido ou não reconhecido. Use 0, 1, 2 ou slugs documentados.
CrmConfig.NameMaxLengthExceeded	400	name excede o máximo do tipo (4000 / 40 / 40).
CrmConfig.NotFound	404	id inexistente em GET, PUT ou DELETE.
CrmConfigCreate.Fail	409 / falha	Falha ao persistir na criação.
CrmConfigUpdate.Fail	409 / falha	Falha ao persistir na actualização.
CrmConfigDelete.Fail	409 / falha	Falha ao eliminar (ex.: dependências ou erro de armazenamento).

As respostas de erro seguem o padrão HTTP da API (Problem Details).

---

Notas de integração

• Use Content-Type: application/json e propriedades em camelCase no corpo.
• Para listagens longas, envie page e pageSize explícitos — o servidor não expõe filtro de texto na listagem.
• Teste os três tipos (0, 1, 2) em staging: os limites de name diferem entre categorias e estados/prioridades.
• O identificador id é gerado na criação; não envie id no POST.

---

Conclusão

A configuração CRM expõe um CRUD unificado sobre /gateway/crm-config/{configType} para categorias, estados e prioridades, com listagem paginada (totalCount, pageSize, currentPage, totalPages, data). Recomenda-se usar 0, 1 e 2 como configType nas integrações.

---

Última actualização: 2 de Junho de 2026