Emit a health document — Health invoices

POST/api/v1/workspaces/{workspaceId}/health-invoices

Operation ID: healthInvoices.emit · Access: PAT with send scope and authorized workspace where applicable · Effect: external.

An Idempotency-Key is required. Retry the same intent with the same key and the same request bytes. Read the retry rules.

Read the health invoices workflow before this operation.

Parameters

Name	In	Required	Type / allowed values
`workspaceId`	path	Yes	string
`idempotency-key`	header	Yes	string

Request body

Content type: application/json · Required: yes.

Schema: EmitHealthInvoiceInput. Browse schema fields.

Example: healthInvoice

Synthetic contract example. Replace identifiers and clinical data with authorized values. This example does not prove ministry acceptance.

Download JSON

{
  "clientId": "payer-demo-001",
  "invoiceResolutionId": "resolution-demo-001",
  "invoicePayload": {
    "invoice_lines": [
      {
        "description": "Consulta de medicina general (ejemplo sintético)",
        "code": "890201",
        "invoiced_quantity": "1",
        "price_amount": "100000.00",
        "line_extension_amount": "100000.00"
      }
    ],
    "legal_monetary_totals": {
      "line_extension_amount": "100000.00",
      "tax_exclusive_amount": "100000.00",
      "tax_inclusive_amount": "100000.00",
      "payable_amount": "100000.00"
    },
    "payment_form": {
      "payment_form_id": 1,
      "payment_method_id": 10
    },
    "health_fields": {
      "invoice_period_start_date": "2026-09-01",
      "invoice_period_end_date": "2026-09-30",
      "health_type_operation_id": "SS-CUFE",
      "users_info": [
        {
          "provider_code": "110010000101",
          "health_coverage_id": "01",
          "health_contracting_payment_method_id": "04",
          "contract_number": "CONTRATO-DEMO"
        }
      ]
    }
  },
  "rips": {
    "numDocumentoIdObligado": "900123456",
    "numFactura": null,
    "tipoNota": null,
    "numNota": null,
    "usuarios": [
      {
        "tipoDocumentoIdentificacion": "CC",
        "numDocumentoIdentificacion": "1000000002",
        "tipoUsuario": "01",
        "fechaNacimiento": "1990-01-01",
        "codSexo": "F",
        "codPaisResidencia": "170",
        "codPaisOrigen": "170",
        "codMunicipioResidencia": "11001",
        "codZonaTerritorialResidencia": "01",
        "incapacidad": "NO",
        "consecutivo": 1,
        "servicios": {
          "consultas": [
            {
              "codPrestador": "110010000101",
              "fechaInicioAtencion": "2026-09-01 10:00",
              "numAutorizacion": null,
              "codConsulta": "890201",
              "modalidadGrupoServicioTecSal": "01",
              "grupoServicios": "01",
              "codServicio": 325,
              "finalidadTecnologiaSalud": "44",
              "causaMotivoAtencion": "38",
              "codDiagnosticoPrincipal": "Z000",
              "codDiagnosticoRelacionado1": null,
              "codDiagnosticoRelacionado2": null,
              "codDiagnosticoRelacionado3": null,
              "tipoDiagnosticoPrincipal": "01",
              "tipoDocumentoIdentificacion": "CC",
              "numDocumentoIdentificacion": "1000000001",
              "vrServicio": 100000,
              "conceptoRecaudo": "05",
              "valorPagoModerador": 0,
              "numFEVPagoModerador": null,
              "consecutivo": 1
            }
          ]
        }
      }
    ]
  }
}

Responses

HTTP	Content	Schema
201	`application/json`	HealthInvoice
202	`application/json`	HealthInvoice
400	`application/json`	ApiError
401	`application/json`	ApiError
403	`application/json`	ApiError
404	`application/json`	ApiError
409	`application/json`	ApiError
413	`application/json`	ApiError
415	`application/json`	ApiError
422	`application/json`	ApiError
428	`application/json`	ApiError
500	`application/json`	ApiError
502	`application/json`	ApiError
503	`application/json`	ApiError

Use error.code, error.issues, and requestId for JSON errors. Error and recovery guide.

cURL

Set the connection variables from the quickstart. Set each path variable to an authorized identifier or an allowed parameter value from the table above.

Save your authorized JSON input as request.json. Use the request schema and examples above; replace synthetic data before use.

Set IDEMPOTENCY_KEY to a unique key for this intent. Preserve it and the exact request for retries.

curl --fail-with-body --request POST \
  "$RIPSCLOUD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/health-invoices" \
  --header "Authorization: Bearer $RIPSCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json