Correspondência

A correspondência enviada para uma fração, e o envio de mensagens em nome da empresa.

Consultar a correspondência de uma fração

GET /fractions/{idFraction}/correspondence

Permissão · correspondence:read

Parâmetros

Parâmetro	Tipo	Por omissão	Descrição
idFraction	inteiro	—	No caminho. A fração
emailOnly	booleano	false	Apenas o que foi enviado por correio eletrónico
fromDate	data	—	A partir desta data
toDate	data	—	Até esta data, inclusive
limit	inteiro	100	Registos por página, no máximo 500
cursor	texto	—	Cursor da página seguinte

Pedido

curl "https://servidor.exemplo/api/integrations/v1/acme/fractions/340/correspondence?emailOnly=true" \
  -H "ApiKey: $GC_API_KEY"

Resposta · 200

{
  "Items": [
    {
      "Id": 7781,
      "IdFraction": 340,
      "Reference": "2026/7781",
      "Date": "2026-09-14T11:22:00",
      "Subject": "Aviso de quota - Setembro 2026",
      "CorrespondenceType": { "Id": 2, "Description": "Aviso de pagamento" },
      "Tag": "AV",
      "Expedition": { "Id": 1, "Description": "Correio eletrónico" },
      "ExpeditionTag": "EM",
      "Opens": 3,
      "HasFile": true
    }
  ],
  "Paging": { "Limit": 100, "NextCursor": null, "HasMore": false }
}

Campo	Tipo	Descrição
Id	inteiro	Identificador
IdFraction	inteiro	A fração a que pertence
Reference	texto	Referência da comunicação
Date	data e hora	Quando foi expedida
Subject	texto	Assunto
CorrespondenceType	objeto	Tipo de comunicação
Tag	texto	Sigla do tipo
Expedition	objeto	Meio de expedição — correio eletrónico, carta, correio registado
ExpeditionTag	texto	Sigla do meio
Opens	inteiro	Quantas vezes um correio eletrónico foi aberto. Fica a 0 nos restantes meios
HasFile	booleano	Existe um documento arquivado

A ordem é da mais recente para a mais antiga.

O documento não é servido pela API

HasFile diz que existe, mas não há ponto de descarga para documentos de correspondência. Só os anexos de ocorrências e de intervenções se descarregam.

Erros

Estado	Código	Quando
400	INVALID_CURSOR	O cursor não foi emitido por esta API
401 · 403		Ver Autenticação e Permissões
404	FRACTION_NOT_FOUND	Não existe fração com esse identificador

Não há correspondência por ocorrência

A correspondência pertence a uma fração, não a uma ocorrência. Não existe forma de perguntar "que mensagens foram trocadas sobre esta ocorrência" — se precisa dessa ligação, tem de a manter do seu lado.

---

Enviar uma mensagem

POST /emails

Permissão · correspondence:send · aceita Idempotency-Key

Envia uma mensagem em nome da empresa de condomínios: sai pela mesma fila de todo o correio da aplicação, com o modelo gráfico da empresa, e é indistinguível de uma enviada de dentro.

Esta permissão fala pela empresa

Quem recebe vê uma mensagem da administração do condomínio, não da sua integração. Use-a com o cuidado que isso exige, e confirme as autorizações de contacto da pessoa antes de lhe escrever.

Corpo

Campo	Tipo	Descrição
IdBuilding ou BuildingCode	inteiro / texto	Obrigatório. O condomínio em nome do qual se envia
IdFraction	inteiro	A fração. É o que faz a mensagem ficar registada
To	texto	Obrigatório. Endereço do destinatário
Subject	texto	Obrigatório. Assunto
Body	texto	Obrigatório. Corpo da mensagem
Attachments	lista	Até 3 anexos, cada um com FileName e ContentBase64

Pedido

curl -X POST "https://servidor.exemplo/api/integrations/v1/acme/emails" \
  -H "ApiKey: $GC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "BuildingCode": "0012",
        "IdFraction": 340,
        "To": "maria.silva@exemplo.pt",
        "Subject": "Reparação da infiltração na garagem",
        "Body": "Informamos que a reparação foi concluída a 25 de setembro.",
        "Attachments": [
          { "FileName": "relatorio.pdf", "ContentBase64": "JVBERi0xLjQK..." }
        ]
      }'

Resposta · 202

{ "Recorded": true }

É 202 e não 201 de propósito: a mensagem foi aceite para envio, e quem a envia é a fila. A resposta chega antes de o correio sair.

Campo	O que diz
Recorded	Se a mensagem também ficou registada como correspondência da fração

Sem fração, não fica registada

Esta é a regra que mais surpreende, por isso vale a pena ser explícito:

Enviou com	A mensagem sai	Fica em /fractions/{id}/correspondence
IdFraction preenchido	sim	sim
IdFraction em falta	sim	não, e não deixa rasto nenhum

A correspondência pertence a uma fração, e uma mensagem endereçada a um fornecedor, a uma seguradora ou a qualquer terceiro não tem onde ser arquivada. É enviada na mesma — mas se depois for procurá-la, não a encontra.

O campo Recorded da resposta diz-lhe exatamente o que aconteceu, para não ter de o deduzir. O ping também o declara, em email.recordedOnlyWithFraction.

Anexos

No máximo três por mensagem — é o que a fila de envio comporta. Um quarto anexo responde 400 TOO_MANY_ATTACHMENTS em vez de ser descartado em silêncio.

Dê sempre o FileName com a extensão correta: é dela que sai o tipo do anexo no correio enviado.

Erros

Estado	Código	Quando
400	INVALID_BODY	Corpo em falta ou JSON inválido
400	MISSING_FIELD	Falta to, Subject ou Body. to também falha se não tiver @
400	INVALID_REFERENCE	A IdFraction não existe, ou não pertence a esse condomínio
400	TOO_MANY_ATTACHMENTS	Mais de três anexos
401 · 403		Ver Autenticação e Permissões
404	BUILDING_NOT_FOUND	O condomínio não existe, nem por identificador nem por código
409	IDEMPOTENCY_KEY_REUSED	A chave já foi usada noutro pedido
422	EMAIL_NOT_QUEUED	A mensagem não foi aceite para envio. Reporte

Use sempre chave de idempotência aqui

Repetir um envio depois de um tempo esgotado manda a mensagem duas vezes ao condómino. É dos poucos sítios em que o erro é visível para o cliente final da empresa. Ver Idempotência.