Gestação
A gestação é o acompanhamento pré-natal da paciente na Nilo: quando começou, o risco, se é única ou múltipla, e como terminou — em parto ou em aborto. Cada paciente tem no máximo uma gestação em curso por vez.
No FHIR ela é uma Observation com o código LOINC
82810-3 (Pregnancy status). É uma observação só por gestação, não uma por dado: o
status vai em valueCodeableConcept, e DUM, DPP, data do parto, risco e tipo vão cada um num
component da mesma observação.
A gestação é, hoje, o único tipo de Observation que a Nilo aceita. O endpoint é genérico,
mas um code sem o LOINC 82810-3 é recusado com not-supported — não há como gravar
sinais vitais, resultados de exame ou outras observações por aqui.
Campos
Os component são reconhecidos pelo code, não pela posição na lista, e a ordem em que você
os manda não importa.
Campos que a Nilo não usa
A Observation canônica tem campos que esta integração não lê nem grava: basedOn,
partOf, category, focus, encounter, issued, performer, dataAbsentReason,
interpretation, note, bodySite, method, specimen, device, referenceRange,
hasMember, derivedFrom e todo value[x] que não seja valueCodeableConcept. Ficam fora da
referência de propósito. O servidor os aceita, guarda no recurso FHIR e devolve nas leituras
seguintes, mas nada na plataforma passa a usá-los.
effectiveDateTime, effectiveInstant e effectiveTiming são diferentes: eles não são
ignorados, são recusados. O único effective[x] aceito é effectivePeriod.
Um component com um code que não está na tabela acima não é erro: é ignorado na escrita e
some do recurso na regravação. O mesmo vale para a DPP que você enviar — ela não é lida, e a
leitura traz a que a plataforma calculou.
Catálogos
Os três catálogos da gestação são da Nilo, e o system de cada um é
{host}/fhir/resources/CodeSystem/<nome>.
Status
O status vai em valueCodeableConcept, num coding com o system
{host}/fhir/resources/CodeSystem/pregnancy-status. Ele é obrigatório: sem esse coding,
a escrita é recusada, mesmo que venha um LOINC.
O coding LOINC no system http://loinc.org é opcional. Se vier, tem de concordar com o
status da Nilo pela tabela acima; um LOINC que contradiz o status é recusado com
business-rule, e um LOINC fora desses dois códigos, com code-invalid. Na leitura, os dois
coding vêm sempre.
Risco
component com o code risk no system {host}/fhir/resources/CodeSystem/pregnancy-observation,
e o valor em valueCodeableConcept no system {host}/fhir/resources/CodeSystem/pregnancy-risk:
Tipo
component com o code LOINC 57722-1, e o valor em valueCodeableConcept no system
{host}/fhir/resources/CodeSystem/pregnancy-type:
Esses catálogos são fixos e estão completos nesta página. Ao contrário do flag-code, eles
não são servidos por GET /fhir/resources/CodeSystem/{nome} — veja
Catálogo de códigos.
Cadastrar ou atualizar
Não há endpoint separado para criar e atualizar. O mesmo POST faz os dois, e quem decide é
o identifier: se já existir uma gestação com aquele par system + value, ela é
atualizada; se não existir, é criada.
A resposta devolve o recurso como ficou gravado, sem envelope:
Ao lado do seu identificador vem o identificador Nilo da gestação, no system
…/NamingSystem/hippocrates-api--pregnancy. Ele também serve para atualizar: é o que você usa
para mexer numa gestação que foi criada na plataforma, e não por você — veja
Uma gestação em curso por paciente.
O identifier não é exigido pela validação, e é por isso que ele é obrigatório na prática:
sem identificador a API não tem como reconhecer a gestação, e cada POST tenta criar uma
nova — que é recusada enquanto a paciente tiver uma gestação em curso. Mande sempre a sua
chave.
A paciente
subject é obrigatório e tem de trazer um identifier da paciente; só reference não basta.
A paciente tem de existir — a gestação não cria paciente. Cadastre a
Paciente primeiro.
A paciente de uma gestação não muda. Reenviar um identifier já gravado apontando para
outra paciente é recusado com business-rule; para registrar a gestação de outra paciente,
use um identifier novo.
Só pacientes do sexo biológico feminino podem ter gestação. Essa regra é da plataforma, não da
integração: a recusa vem com business-rule e a mensagem que a plataforma devolver, sem
expression.
Datas
Toda data da gestação exige data completa. 2026-03 ou 2026 são recusados com invalid.
- DUM. Vem do
component8665-2. Sem ele, a API lêeffectivePeriod.startcomo DUM. Vindo os dois, vale ocomponent. - Data do parto. Vem do
component93857-1. - Data de encerramento. Vem de
effectivePeriod.end— veja Encerrar uma gestação.
Nos component, a hora é descartada: só o dia é gravado. Em effectivePeriod.end a hora é
mantida; um end só com a data é lido como meia-noite, e um end com hora e sem fuso, como
horário de Brasília (America/Sao_Paulo).
Na leitura, effectivePeriod.start não é sempre a DUM: numa gestação sem DUM, ele traz a
data em que a gestação foi criada na plataforma. Como a escrita lê start como DUM quando
falta o component 8665-2, reenviar esse recurso como foi lido grava a data de criação
como DUM.
Se o seu integrador lê gestações e as reenvia, confira o component 8665-2 antes: se ele não
veio, retire effectivePeriod.start do payload.
Atualização parcial
A gestação aceita atualização parcial. Risco, tipo, DUM e data do parto só são gravados
quando vêm no payload: um component ausente mantém o valor que já estava lá.
Três dados, porém, são sempre aplicados: a paciente, o status e a data de encerramento. O status é obrigatório em todo envio, e é ele que decide a data de encerramento.
O status enviado substitui o gravado, sem exceção. Reenviar uma gestação encerrada com
prenatal — um payload antigo, guardado antes do encerramento, por exemplo — apaga a data de
encerramento. Não guarde payloads de gestação para reenvio: monte o envio a partir do status
atual.
Encerrar uma gestação
Uma gestação termina quando o status muda para postpartum (parto) ou abortion (aborto). A
data de encerramento é escolhida nesta ordem:
effectivePeriod.end, se vier no payload;- senão, a data de encerramento que já estava gravada;
- senão, em
abortion, o momento da gravação; - senão, em
postpartum, a meia-noite (horário de Brasília) do dia do parto — o docomponent93857-1do payload ou, sem ele, o já gravado; - sem nenhuma dessas,
postpartumé recusado comrequired.
Em prenatal, effectivePeriod.end é recusado com business-rule: para encerrar, mude o
status.
Não há como apagar uma gestação por esta API: a escrita nunca responde 204, e
entered-in-error e cancelled em status são recusados. Uma gestação registrada por engano
tem de ser removida na plataforma; a remoção é propagada para o store FHIR pela
sincronização.
Uma gestação em curso por paciente
A paciente tem no máximo uma gestação prenatal. Enviar uma gestação com um identifier novo
enquanto ela tem outra em curso é recusado:
A recusa costuma aparecer quando a gestação em curso foi registrada na plataforma, e o seu sistema não conhece a chave dela. Para atualizá-la:
- Busque as gestações da paciente:
GET /fhir/resources/Observation?patient.identifier=<system>|<value>&code=http://loinc.org|82810-3. - Pegue, na gestação
prenatal, um dosidentifier— o identificador Nilo, nosystem…/NamingSystem/hippocrates-api--pregnancy, sempre está lá. - Reenvie a gestação com esse
identifier. Pode mandar o seu junto, na mesma lista.
Para registrar uma gestação nova, encerre a atual antes (postpartum ou abortion). Uma gestação
encerrada não impede o registro de uma nova.
Erros
Recusa é 400, e o corpo é um OperationOutcome: issue[].expression aponta o campo culpado
e issue[].details.text explica o motivo.
Os payloads completos das recusas mais comuns estão na aba Referência, em
POST /fhir/resources/Observation. Três deles:
Buscar
A resposta é sempre um Bundle do tipo searchset, mesmo quando há um único resultado:
Busca sem resultados não é erro: volta 200 com um Bundle cujo entry é uma lista vazia.
Trate a ausência de resultados pela lista vazia, não esperando um 404.
A busca traz todas as Observation do store, não só as gestações. Hoje as duas coisas
coincidem, mas inclua code=http://loinc.org|82810-3 nas suas buscas para que elas continuem
trazendo só gestações quando outros tipos de observação forem aceitos.
Parâmetros de busca suportados
Para trazer só as gestações em curso de uma paciente:
Qual identificador da paciente o subject carrega depende da sua implantação. Na
configuração que usa identificadores externos nas referências, é o identificador do seu
sistema — e o filtro acima funciona como está. Sem ela, o subject traz o identificador Nilo
da paciente (…/NamingSystem/hippocrates-api--patient), e é esse system que você tem de
usar no filtro. Confira numa resposta de leitura qual dos dois está lá antes de montar a
busca em volume.
status não serve para filtrar gestações: toda gestação é lida com status final. Para
separar as em curso das encerradas, use value-concept.
date filtra pelo effectivePeriod, cujo início é a DUM ou, sem ela, a data de criação da
gestação — veja Datas.
A paginação é por _count e _page_token; havendo página seguinte, o Bundle traz a URL
pronta em link.
Ler por ID
A leitura por ID responde 404 quando o id não existe.
Diferente da busca, esta leitura não devolve um Bundle — mas também não devolve o recurso
nu. A resposta é um envelope com fullUrl, search e resource, e a gestação está em
resource. Ler valueCodeableConcept ou component na raiz da resposta não encontra nada.
Nem tudo o que você lê foi escrito por esta API. Gestações registradas pela equipe na plataforma aparecem aqui do mesmo jeito, com o identificador Nilo e sem o seu.
O que a integração não cobre
Não há como apagar uma gestação, nem registrar outro tipo de observação além da gestação. A DPP não é gravável: é sempre a que a plataforma calcula a partir da DUM.