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

```text
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](/guides/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](/reference/operations/rips-packages-create/). A `sourcePackageId` does not replace the reference checks.

## Save a draft

Download a [synthetic RIPS-without-invoice example](/examples/rips-packages-create-rips_sin_factura.json). Replace all provider, patient, professional, service, and date values with authorized data before use.

```bash
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.

```http
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](/reference/operations/rips-packages-revise/). Never send server-owned status, revision, or CUV fields. A new revision invalidates the previous validation.

## Validate the current revision

```bash
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.

```bash
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](/reference/operations/rips-packages-list-dispatches/). 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](/reference/operations/rips-packages-reconcile/) 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.