Autenticação

Emite access token (OAuth 2.0 client_credentials)

POST /oauth/token

Sem token: credenciais no corpo
Limite 10/min por IP

Credenciais no corpo (JSON ou formulário); HTTP Basic do cliente não é aceito. Credencial inexistente, segredo errado e integração revogada respondem o mesmo 401. A resposta tem Cache-Control: no-store.

Corpo da requisição

grant_type string obrigatório

Valores: client_credentials

client_id string obrigatório

Identificador público (cli_...).

até 64 caracteres

client_secret string obrigatório

Segredo (cs_...), exibido só na criação/troca.

até 255 caracteres

scope string (anulável)

Escopos separados por espaço, contidos nos da integração. Ausente/vazio = todos os escopos da integração. Escopo desconhecido → 422 FIELD_ENUM_INVALID.

até 500 caracteres

Respostas

200 Token emitido (válido por 1 hora; não há refresh token).

access_token string obrigatório

Token opaco (cat_...).

token_type string obrigatório

Valores: Bearer

expires_in integer obrigatório

Validade em segundos (3600).

scope string obrigatório

Escopos concedidos, separados por espaço.

401 Credenciais inválidas ou integração revogada. Códigos possíveis: AUTH_CREDENTIALS_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

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.

403 Escopo pedido fora do liberado à integração, ou empresa sem acesso. Códigos possíveis: AUTH_SCOPE_INSUFFICIENT, AUTH_TENANT_SUSPENDED, AUTH_TENANT_PLAN_WITHOUT_API.

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.

422 Dados inválidos — detalhes em errors/error_codes.

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.

429 Mais de 10 emissões por minuto do mesmo IP. 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/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"cli_exemplo","client_secret":"cs_exemplo"}'

PHP

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

$response = $client->request('POST', 'oauth/token', [
    'headers' => ['Accept' => 'application/json'],
    'json' => [
        'grant_type' => 'client_credentials',
        'client_id' => 'cli_exemplo',
        'client_secret' => 'cs_exemplo',
    ],
    'http_errors' => false,
]);

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

Node.js

const response = await fetch('https://cuidaro.com.br/api/v1/oauth/token', {
  method: 'POST',
  headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "grant_type": "client_credentials",
    "client_id": "cli_exemplo",
    "client_secret": "cs_exemplo"
  }),
});
const data = response.status === 204 ? null : await response.json();

Python

import requests

response = requests.request(
    "POST",
    "https://cuidaro.com.br/api/v1/oauth/token",
    headers={"Accept": "application/json"},
    json={
        "grant_type": "client_credentials",
        "client_id": "cli_exemplo",
        "client_secret": "cs_exemplo",
    },
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

Resposta 200

{
  "access_token": "cat_exemplo",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "texto"
}

Erro 422 (exemplo)

{
  "type": "https://cuidaro.com.br/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "Os dados enviados são inválidos.",
  "instance": "/api/v1/oauth/token",
  "code": "VALIDATION_FAILED"
}