Ordens de serviço

Cancela OS criada pela API, faturada ou ainda não faturada (operação estrita)

POST /service-orders/{serviceOrder}/cancel

Escopo services:write
Idempotency-Key obrigatória · estrita
Limite escrita 60/min

OS faturada pela API: estorna o recebimento informado no faturamento (uma única vez), cancela recebível e OS e pede o cancelamento da NFS-e. Repetir (com chave nova) só repete o passo fiscal. OS ainda não faturada (como a OS recém-criada pela API, em awaiting_invoice, sem nota): é cancelada e responde 202 com meta.fiscal_cancellation = cancelled e data.fiscal = null (contrato garantido; útil quando o estorno chega antes do faturamento). OS faturada pela tela do Cuidaro → 409 RESOURCE_STATE_CONFLICT.

Parâmetros

Idempotency-Key string · cabeçalho obrigatório

Chave de idempotência — operação estrita (api.idempotent:strict): a chave "executando" nunca é retomada antes de vencer (24 h); todo reenvio com ela recebe 409 IDEMPOTENCY_KEY_IN_PROGRESS. Consulte o recurso pelo GET e, se a operação não aconteceu, reenvie com chave nova. Demais regras iguais às da operação comum.

até 255 caracteres

Corpo da requisição

reason string (anulável)

até 500 caracteres

Respostas

202 OS cancelada (status: cancelled); cancelamento fiscal em meta.fiscal_cancellation.

data object obrigatório

id integer obrigatório

number string (anulável) obrigatório

status string obrigatório

Vocabulário público da OS. unknown quando o estado interno não tem correspondência.

Valores: open in_progress awaiting_invoice invoiced closed cancelled unknown

external_reference string (anulável) obrigatório

contact_id integer (anulável) obrigatório

Sem dado pessoal na OS — use GET /contacts/{contact}.

items array de object obrigatório

id integer obrigatório

service_id integer (anulável) obrigatório

description string (anulável) obrigatório

quantity string obrigatório

String decimal com 3 casas.

unit_price string obrigatório

Valor monetário em string decimal com 2 casas.

total string obrigatório

Valor monetário em string decimal com 2 casas.

total string obrigatório

Valor monetário em string decimal com 2 casas.

receivables array de object obrigatório

id integer obrigatório

status string obrigatório

Valores: pending overdue paid cancelled unknown

amount string obrigatório

Valor monetário em string decimal com 2 casas.

amount_paid string obrigatório

Valor monetário em string decimal com 2 casas.

due_date string (anulável) obrigatório

formato date

payment_date string (anulável) obrigatório

formato date

settlement object (anulável) obrigatório

Pagamento externo informado no faturamento pela API, ou null.

type string obrigatório

Valores: external

gateway string obrigatório

gateway_reference string obrigatório

method string obrigatório

paid_at string obrigatório

formato date

amount string obrigatório

Valor monetário em string decimal com 2 casas.

reversed_at string (anulável) obrigatório

formato date-time

fiscal object (anulável) obrigatório

NFS-e mais recente da OS (somente leitura), ou null.

type string obrigatório

Valores: nfse

status string obrigatório

Valores: pending processing issued rejected cancelled cancellation_pending cancellation_error

number string (anulável) obrigatório

null até o provedor informar.

issued_at string (anulável) obrigatório

formato date-time

cancellation_requested_at string (anulável) obrigatório

formato date-time

cancelled_at string (anulável) obrigatório

formato date-time

pdf_url string (anulável) obrigatório

Link assinado do Cuidaro, válido por 24 h; só para nota emitida ou cancelada.

formato uri

xml_url null obrigatório

Ainda não oferecido (sempre null).

created_at string (anulável) obrigatório

formato date-time

billed_at string (anulável) obrigatório

formato date-time

updated_at string (anulável) obrigatório

formato date-time

meta object obrigatório

operation string obrigatório

Valores: cancel

fiscal_cancellation string obrigatório

Valores: cancellation_pending cancelled cancellation_request_failed

404 Recurso inexistente, excluído ou de outra empresa/integração. Códigos possíveis: RESOURCE_NOT_FOUND.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

Catálogo estável de códigos de erro (App\Enums\ApiErrorCode). Código publicado nunca é renomeado nem removido; códigos novos podem surgir — trate valor desconhecido como erro genérico do status HTTP. O status, o título e o type de cada código estão em x-cuidaro-error-catalog.

Valores: AUTH_CREDENTIALS_INVALID AUTH_TOKEN_EXPIRED AUTH_TOKEN_MISSING AUTH_TOKEN_INVALID AUTH_SCOPE_INSUFFICIENT AUTH_TENANT_SUSPENDED AUTH_TENANT_PLAN_WITHOUT_API ACCESS_DENIED BAD_REQUEST VALIDATION_FAILED FIELD_REQUIRED FIELD_TYPE_INVALID FIELD_MAX_LENGTH FIELD_ENUM_INVALID FIELD_INVALID IDEMPOTENCY_KEY_MISSING IDEMPOTENCY_KEY_INVALID IDEMPOTENCY_KEY_CONFLICT IDEMPOTENCY_KEY_IN_PROGRESS RESOURCE_NOT_FOUND METHOD_NOT_ALLOWED RESOURCE_STATE_CONFLICT PLAN_QUOTA_EXCEEDED PAYLOAD_TOO_LARGE RATE_LIMIT_EXCEEDED HTTP_ERROR INTERNAL_ERROR SERVICE_UNAVAILABLE WEBHOOK_URL_NOT_ALLOWED RESOURCE_ALREADY_EXISTS SETTLEMENT_AMOUNT_MISMATCH EXTERNAL_SETTLEMENT_NOT_ALLOWED EXTERNAL_SETTLEMENT_ACCOUNT_MISSING

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

409 OS faturada pela tela (sem pagamento informado pela API) ou em estado que não permite cancelar, ou conflito de idempotência. Códigos possíveis: RESOURCE_STATE_CONFLICT, IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_IN_PROGRESS.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

422 Dados inválidos, ou Idempotency-Key ausente/inválida. Também: IDEMPOTENCY_KEY_MISSING, IDEMPOTENCY_KEY_INVALID.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

errors object

Mensagens por campo (pt-BR).

error_codes object

Códigos estáveis por campo: FIELD_REQUIRED, FIELD_TYPE_INVALID, FIELD_MAX_LENGTH, FIELD_ENUM_INVALID, FIELD_INVALID, WEBHOOK_URL_NOT_ALLOWED.

401 Token ausente, inválido, revogado ou expirado. Códigos: AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, AUTH_TOKEN_EXPIRED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

403 Escopo insuficiente ou empresa sem acesso à API. Códigos possíveis: AUTH_SCOPE_INSUFFICIENT, AUTH_TENANT_SUSPENDED, AUTH_TENANT_PLAN_WITHOUT_API, ACCESS_DENIED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

413 Corpo acima de 512 KB. Códigos possíveis: PAYLOAD_TOO_LARGE.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

429 Limite de requisições excedido. Código: RATE_LIMIT_EXCEEDED.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

500 Erro interno, sem mensagem interna nem stack trace. Códigos possíveis: INTERNAL_ERROR.

type string obrigatório

https://cuidaro.com.br/errors/{slug} — ainda não é endereço navegável.

formato uri

title string obrigatório

Título curto e estável por código (inglês).

status integer obrigatório

detail string obrigatório

Texto para pessoas, em pt-BR. Pode mudar; não use para lógica.

instance string obrigatório

Caminho da requisição (ex.: /api/v1/me).

code string obrigatório

metric string

Só em PLAN_QUOTA_EXCEEDED: métrica do plano atingida.

limit integer (anulável)

Só em PLAN_QUOTA_EXCEEDED: limite do plano.

existing_resource_id integer

Só em RESOURCE_ALREADY_EXISTS: id do recurso que já existe.

expected_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: total da OS.

received_amount string

Só em SETTLEMENT_AMOUNT_MISMATCH: valor recebido em settlement.amount.

service_order_status string

Só no RESOURCE_STATE_CONFLICT do faturamento: status público atual da OS.

Requisição

cURL

curl -X POST 'https://cuidaro.com.br/api/v1/service-orders/731/cancel' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-900-estorno' \
  -d '{"reason":"Estorno do pedido 900"}'

PHP

// composer require guzzlehttp/guzzle
$client = new \GuzzleHttp\Client(['base_uri' => 'https://cuidaro.com.br/api/v1/']);
$token = getenv('CUIDARO_TOKEN');

$response = $client->request('POST', 'service-orders/731/cancel', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token, 'Idempotency-Key' => 'pedido-900-estorno'],
    'json' => [
        'reason' => 'Estorno do pedido 900',
    ],
    'http_errors' => false,
]);

$data = json_decode((string) $response->getBody(), true);

Node.js

const token = process.env.CUIDARO_TOKEN;

const response = await fetch('https://cuidaro.com.br/api/v1/service-orders/731/cancel', {
  method: 'POST',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'pedido-900-estorno' },
  body: JSON.stringify({
    "reason": "Estorno do pedido 900"
  }),
});
const data = response.status === 204 ? null : await response.json();

Python

import os

import requests

token = os.environ["CUIDARO_TOKEN"]

response = requests.request(
    "POST",
    "https://cuidaro.com.br/api/v1/service-orders/731/cancel",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}", "Idempotency-Key": "pedido-900-estorno"},
    json={
        "reason": "Estorno do pedido 900",
    },
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 202

{
  "data": {
    "id": 731,
    "number": "1000",
    "status": "open",
    "external_reference": "pedido-900",
    "contact_id": 4812,
    "items": [
      {
        "id": 731,
        "service_id": 12,
        "description": "texto",
        "quantity": "1.000",
        "unit_price": "149.90",
        "total": "149.90"
      }
    ],
    "total": "149.90",
    "receivables": [
      {
        "id": 731,
        "status": "pending",
        "amount": "149.90",
        "amount_paid": "149.90",
        "due_date": "2026-10-27",
        "payment_date": "2026-10-27"
      }
    ],
    "settlement": {
      "type": "external",
      "gateway": "asaas",
      "gateway_reference": "pay_exemplo900",
      "method": "pix",
      "paid_at": "2026-10-27",
      "amount": "149.90",
      "reversed_at": "2026-10-27T11:00:00-03:00"
    },
    "fiscal": {
      "type": "nfse",
      "status": "pending",
      "number": "1000",
      "issued_at": "2026-10-27T11:00:00-03:00",
      "cancellation_requested_at": "2026-10-27T11:00:00-03:00",
      "cancelled_at": "2026-10-27T11:00:00-03:00",
      "pdf_url": "https://cuidaro.com.br/…",
      "xml_url": null
    },
    "created_at": "2026-10-27T11:00:00-03:00",
    "billed_at": "2026-10-27T11:00:00-03:00",
    "updated_at": "2026-10-27T11:00:00-03:00"
  },
  "meta": {
    "operation": "cancel",
    "fiscal_cancellation": "cancellation_pending"
  }
}

Erro 422 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/idempotency-key-missing",
  "title": "Idempotency Key Missing",
  "status": 422,
  "detail": "Envie o cabeçalho Idempotency-Key nesta operação.",
  "instance": "/api/v1/service-orders/731/cancel",
  "code": "IDEMPOTENCY_KEY_MISSING"
}