> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.nilo.services/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.nilo.services/_mcp/server.

# Escritas

> Como o POST faz upsert por identificador e o que a API devolve em cada desfecho.

Não existe endpoint separado para criar e para atualizar. Todo envio é um `POST` no tipo do
recurso, e o que decide entre criar e atualizar é o **identificador**.

## Upsert por identificador

Todo recurso carrega um ou mais `identifier`, cada um com `system` (o namespace, uma URI que
identifica o seu sistema) e `value` (a chave daquele registro no seu sistema):

```json
{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "https://www.acmesaude.com.br/integracao/paciente/",
      "value": "507823709"
    }
  ]
}
```

Se já existir um recurso com aquele identificador, ele é **atualizado**. Se não existir, é
**criado**. Reenviar o mesmo payload duas vezes não gera duplicata — é o que torna a
integração segura para reprocessamento.

> **Note**
>
> Mantenha o `system` estável ao longo do tempo. Trocar o `system` de um paciente já integrado
> faz a Nilo tratá-lo como um paciente novo, e o histórico fica partido em dois registros.

## O que a API devolve

A escrita é síncrona: o processamento já terminou quando a resposta chega, e o corpo da
resposta é o recurso gravado.

| Status | Significado                                                                    |
| ------ | ------------------------------------------------------------------------------ |
| `200`  | Gravado. O corpo é o recurso FHIR resultante, já com `id` e `meta.versionId`.  |
| `204`  | Processado, sem recurso a devolver — é o caso das operações de remoção lógica. |
| `400`  | Rejeitado. O corpo é um `OperationOutcome` com o motivo.                       |
| `429`  | Limite de escrita atingido para aquele tipo de recurso.                        |

A validação acontece **antes** da gravação. Um payload que não passa na validação FHIR é
recusado sem criar nada.

## Várias escritas de uma vez

Para agrupar várias escritas numa requisição só — inclusive criando um recurso e outro que o
referencia no mesmo envio —, veja [Carga em lote](/guia/operacoes/carga-em-lote).

Para ser **avisado** quando um recurso mudar, em vez de consultar,
veja [Webhooks](/guia/operacoes/webhooks).