The RIPS lifecycle

A reliable integration keeps draft storage, validation, external dispatch, and acceptance as separate steps.

Read context → Save draft → Revise if needed → Validate
                                                ↓
                         Read evidence ← Request dispatch

Read the context

Use GET /api/v1/workspaces/{workspaceId}/rips-packages/context. Use the configured provider code, site, NIT, environment, and catalogs. Check the data model before mapping your service records.

Choose a package type

The production contract defines 11 kinds. Choose the kind for the actual process. Do not choose a type only to bypass a required reference.

Kind	Use	Important dependency
`rips_sin_factura`	RIPS without a companion invoice	RIPS required; no attached document
`fev_rips`	RIPS with a health invoice	RIPS and accepted invoice
`nc_parcial`	Partial credit note	RIPS and accepted credit note; source receipt
`nc_total`	Total credit note	Accepted credit note; source receipt; no RIPS body
`nd`	Debit note	Supplemental RIPS and accepted debit note; source receipt
`nota_ajuste`	RIPS adjustment	RIPS and accepted source package; no attached XML
`capita_inicial`	Initial capitation package	Accepted invoice with modality 03 and contract or policy; no RIPS body
`capita_periodo`	Capitation period package	Zero-value RIPS, an accepted prior capitation receipt, and a new accepted invoice
`capita_final`	Final capitation package	Zero-value RIPS and an accepted prior capitation receipt; no attached XML
`nc_acuerdo_voluntades`	Credit note for an agreement	Accepted credit note and source receipt; no RIPS body
`nc_capita`	Capitation credit note	Accepted credit note and source receipt; no RIPS body

The server verifies required references in the same workspace, destination, and environment. Read the 11 full examples in Create RIPS packages. A sourcePackageId does not replace the reference checks.

Save a draft

Download a synthetic RIPS-without-invoice example. Replace all provider, patient, professional, service, and date values with authorized data before use.

curl --fail-with-body --include \
  "$RIPSCLOUD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/rips-packages" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @package.json

The server returns HTTP 201, a package id, revision, and ETag. Save them. Creating a draft does not send it to the ministry. Drafts can contain incomplete data that validation will reject.

Revise with an ETag

Read the current package first. Send its ETag in If-Match when you patch editable fields.

PATCH /api/v1/workspaces/{workspaceId}/rips-packages/{packageId}
Authorization: Bearer <PAT>
Content-Type: application/json
If-Match: "1"

{ "rips": { "numDocumentoIdObligado": "replace-with-authorized-NIT" } }

The body above only illustrates the patch shape; it is not a complete clinical record. Use the exact revision schema. Never send server-owned status, revision, or CUV fields. A new revision invalidates the previous validation.

Validate the current revision

curl --fail-with-body \
  "$RIPSCLOUD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/rips-packages/$PACKAGE_ID/validations" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"revision":1}'

Replace 1 with the current revision. Read validation.outcome, validation.issues, and the package’s current validation evidence. HTTP 200 can still report invalid data. Correct the issues, then validate the new revision. Validation checks data, context, document references, and current XML where applicable.

Request dispatch

Only dispatch after the current revision is valid and you intend a real external submission. Use a unique idempotency key for this intent.

curl --fail-with-body \
  "$RIPSCLOUD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/rips-packages/$PACKAGE_ID/dispatches" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $DISPATCH_KEY" \
  --data '{"revision":1}'

The server validates again before the external action. Read package.status, attempt, and the returned evidence. HTTP status alone is insufficient.

Package status	Meaning	Client action
`Draft`	Editable package	Validate the current revision
`Dispatching`	An attempt is in progress	Read status; do not submit another attempt
`Accepted`	Verified acceptance receipt	Store the returned evidence and CUV
`Rejected`	Terminal rejection	Read issues; correct through a new revision
`Unknown`	External result is uncertain	Reconcile with evidence; do not resend

HTTP 200 can contain Accepted or Rejected. HTTP 202 can contain Dispatching or Unknown.

Read and recover

Read the package and its dispatch attempts. Poll with bounded backoff. The contract does not publish a polling interval or webhook.

For Unknown, keep the original intent and evidence. If you obtain the ministry CUV through a support channel, use reconciliation with the attempt ID and evidence.cuv. The server verifies that CUV. It cannot discover a CUV from an invoice number. A new idempotency key does not unlock an unknown submission.