Guia de integração — Workspace CRM do cliente

Introdução

Este guia descreve os endpoints de leitura sob /gateway/crm/customers/{keyId} que alimentam a ficha CRM do cliente: cabeçalho da entidade, contactos, moradas adicionais e histórico paginado de vendas e recibos com totais agregados.

Para saldo por escalões de vencimento, contas a receber e liquidação por recibo, consulte o Guia de conta corrente CRM.

O prefixo público é /gateway.

---

Conceitos

Cliente (entityKeyId)

Identificador textual do cliente (até 25 caracteres). Todas as rotas deste guia usam este valor como keyId na URL.

Chave composta do documento

Os documentos de venda e recibo no workspace CRM são identificados por documentTypeId, serieId e number. Use estes três parâmetros de rota para carregar detalhes de pagamento ou linhas de corpo.

---

Endpoints

Método	URL	Descrição
GET	/gateway/crm/customers/{keyId}	Cabeçalho da entidade, contactos e moradas adicionais
GET	/gateway/crm/customers/{keyId}/receipts	Cabeçalhos de recibos paginados e agregado paymentsAmount
GET	/gateway/crm/customers/{keyId}/receipts/{documentTypeId}/{serieId}/{number}/payment-details	Linhas de pagamento agrupadas por tipo
GET	/gateway/crm/customers/{keyId}/sales	Cabeçalhos de vendas paginados e agregado salesTotal
GET	/gateway/crm/customers/{keyId}/sales/{documentTypeId}/{serieId}/{number}/lines	Linhas de corpo de um documento de venda

Parâmetro de rota: keyId — entityKeyId do cliente.

Vendas e recibos são carregados sob demanda: o endpoint do workspace devolve apenas cabeçalho, contactos e moradas. Chame /receipts ou /sales quando o utilizador abrir esses separadores.

Resposta do workspace (200 OK)

{
  "entity": {
    "keyId": "CLI001",
    "name": "Cliente Exemplo Lda",
    "balance": 1250.5,
    "limitCredit": 5000,
    "lastPurchase": "2026-05-20T00:00:00Z"
  },
  "contacts": [
    {
      "id": 1,
      "name": "João Silva",
      "email1": "joao@exemplo.pt",
      "mobilePhone1": "+351900000000"
    }
  ],
  "addresses": [
    {
      "id": 1,
      "addressLine1": "Rua Exemplo 1",
      "city": "Lisboa",
      "postalCode": "1000-001"
    }
  ]
}

O objecto entity inclui campos de resumo financeiro (balance, limitCredit, lastPurchase) juntamente com morada e contactos.

Vendas e recibos paginados

Ambos os endpoints de listagem aceitam parâmetros de consulta opcionais:

Parâmetro	Tipo	Descrição
page	int	Número da página (base 1)
pageSize	int	Registos por página

A resposta segue a estrutura da listagem paginada mais um total agregado:

Endpoint	Campo agregado	Descrição
/receipts	paymentsAmount	Soma dos totais de recibo em todos os documentos correspondentes
/sales	salesTotal	Soma com sinal dos totais de venda (fluxo de caixa aplicado)

Cada item de data inclui documentTypeId, serieId, number, documentIdentifier, createDate e totalAmount. Use a chave de três partes para abrir os endpoints de detalhe.

Campos do cabeçalho de recibo (resumo): otherValues, virtualTotalAmount, salesmanName, observation.

Campos do cabeçalho de venda (resumo): salesmanId, salesmanName, headerDiscountPercent, headerDiscountAmount, observation.

Detalhes de pagamento do recibo

Devolve um array de linhas de pagamento agrupadas por tipo:

Campo	Descrição
paymentTypeId	Identificador do tipo de pagamento
paymentTypeDescription	Descrição do tipo de pagamento
netAmount	Montante líquido para este tipo
paymentMechanism	Código do mecanismo de pagamento
currencyId, currencyRate	Moeda e taxa de câmbio
isChange	Indica se a linha representa troco
bankDetail	Dados bancários quando aplicável (conta, cheque, data diferida, …)

Linhas de corpo da venda

Devolve um array de linhas do documento:

Campo	Descrição
itemKeyId	Identificador do artigo
description	Descrição da linha
quantity	Quantidade
taxIncludedPrice	Preço unitário com IVA
discountPercent	Percentagem de desconto da linha
lineTotal	Total da linha

---

Estrutura da listagem paginada

Campo	Tipo	Descrição
totalCount	int	Total de registos
pageSize	int	Tamanho da página
currentPage	int	Página actual (base 1)
totalPages	int	Total de páginas
data	array	Documentos da página

As respostas de /receipts e /sales acrescentam ainda paymentsAmount ou salesTotal, respectivamente.

---

Exemplos

Workspace do cliente

GET /gateway/crm/customers/CLI001

Ver mais →

Recibos paginados

GET /gateway/crm/customers/CLI001/receipts?page=1&pageSize=20

Ver mais →

Detalhes de pagamento de um recibo

GET /gateway/crm/customers/CLI001/receipts/5/1/100/payment-details

Ver mais →

Vendas paginadas

GET /gateway/crm/customers/CLI001/sales?page=1&pageSize=20

Ver mais →

Linhas de corpo de uma venda

GET /gateway/crm/customers/CLI001/sales/2/1/250/lines

Ver mais →

---

Fluxo recomendado

1. Identificar o cliente — obter entityKeyId.
2. Abrir ficha CRM — GET /gateway/crm/customers/{keyId} para cabeçalho, contactos e moradas.
3. Histórico de vendas ou recibos — GET .../sales ou GET .../receipts ao abrir os separadores.
4. Detalhar documento — usar documentTypeId, serieId e number nos endpoints de linhas ou pagamentos.

Para consultar saldo, dívidas abertas e registar liquidações, siga o Guia de conta corrente CRM.

---

Erros frequentes

Código HTTP	Situação	Acção sugerida
401	Token em falta ou inválido	Autenticar no gateway
404	keyId ou chave de documento inexistente	Confirmar identificadores

---

Conclusão

O workspace CRM do cliente expõe leitura da ficha CRM e do histórico comercial sob /gateway/crm/customers/{keyId}. Carregue vendas e recibos sob demanda e use a chave composta para aceder a linhas de corpo e detalhes de pagamento.

---

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