Respuestas y errores

Respuesta exitosa

Si el envío se acepta, la API responde 202 Accepted. Significa recibido y encolado, no "ya procesado": el impacto en el sistema es asíncrono. El body devuelve un identificador del envío que sirve para consultar el estado más tarde (ver Consultar el estado):

{
  "id": 12345,
  "status": "received",
  "duplicate": false
}

Campo	Descripción
id	Identificador del mensaje en el gateway. Usalo en GET /fhir/{id} para ver el desenlace.
status	Estado interno al momento de aceptar (siempre inicial). Para el desenlace real consultá el endpoint de estado.
duplicate	true si el x-source-message-id ya se había recibido (no se reprocesa).

Errores de validación

Si el envío se rechaza, la API responde un OperationOutcome de FHIR con un código de error estable en issue.details.coding.code:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": { "coding": [{ "code": "PATIENT_NOT_FOUND" }] },
      "diagnostics": "Encounter references patient \"PAC-99\" which does not exist"
    }
  ]
}

Código	HTTP	Significado
INVALID_BUNDLE	400	El body no es un Bundle/recurso FHIR válido
UNSUPPORTED_RESOURCE_TYPE	422	resourceType no soportado
MISSING_IDENTIFIER	422	Falta el identificador de la entidad
MISSING_REFERENCE	422	Falta una referencia obligatoria (p. ej. Encounter.subject)
PATIENT_NOT_FOUND	422	Se referencia un paciente que no existe
ENCOUNTER_NOT_FOUND	422	Se referencia un episodio que no existe
PROCEDURE_NOT_FOUND	422	Se referencia una práctica que no existe
TARGET_NOT_FOUND	422	DocumentReference.subject.type no es Patient/Encounter/Procedure
MESSAGE_NOT_FOUND	404	GET /fhir/{id} de un envío inexistente (o de otro cliente)

Errores de autenticación: 401 (API key faltante/incorrecta o IP no permitida).

Idempotencia

El header x-source-message-id identifica el envío. Si reenviás el mismo id, el envío se trata como duplicado: se responde 202 pero no se reprocesa. Usá un id nuevo por cada envío; reservá el reintento con el mismo id para reintentos ante fallas de red.

Orden y dependencias

El procesamiento tolera el desorden y reintenta, pero cada recurso necesita que su "padre" exista (en el mismo Bundle o enviado antes): una práctica necesita su episodio; un episodio, su paciente. Si preferís, mandá todo junto en un Bundle transaction.

El 202 no garantiza el impacto final

La validación referencial ocurre al recibir (y devuelve error en el momento). Otras reglas de negocio (p. ej. que el plan o el código de práctica existan en los catálogos acordados) se resuelven durante el procesamiento asíncrono. Asegurate de enviar valores de catálogo válidos, acordados en el onboarding.

Consultar el estado del envío

Como el impacto es asíncrono, el desenlace real (se aplicó, fue rechazado por una regla de negocio, o falló) se consulta con:

GET /fhir/{id}

donde {id} es el id que devolvió el 202. Requiere la misma x-api-key. Sólo podés consultar tus propios envíos: un id inexistente o de otro cliente responde 404 (MESSAGE_NOT_FOUND).

{
  "id": 12345,
  "sourceMessageId": "encounter-101",
  "status": "rejected",
  "duplicate": false,
  "receivedAt": "2026-07-29T16:15:15.679Z",
  "results": [
    { "aggregateType": "encounter", "status": "done" },
    { "aggregateType": "authorization", "status": "rejected", "reason": "plan no mapeado" }
  ]
}

• status — estado agregado del envío:

  Estado	Significado	¿Terminal?
  accepted	recibido, todavía sin procesar	no
  processing	en proceso (parte del envío aún en curso)	no
  done	todo el envío impactó correctamente	sí
  rejected	una regla de negocio rechazó parte del envío	sí
  failed	el envío no pudo procesarse tras reintentos	sí
  duplicate	ya se había recibido ese x-source-message-id	sí

• results — detalle por cada recurso del envío (útil cuando un Bundle trae varios): su status individual y, en rejected/failed, un reason con el motivo.

Polling: un envío suele resolverse en segundos. Consultá cada pocos segundos hasta ver un estado terminal (done/rejected/failed/duplicate); evitá pollear en un loop cerrado.