Comece aqui

Primeiros passos

Do pedido de credenciais à primeira chamada autenticada.

Endereço da API

Credenciais

Quem gera as credenciais é o dono ou um administrador da empresa no Cuidaro.

1. Configurações → Integrações (API) → Nova integração. Informe um nome (ex.: "Loja virtual") e marque os escopos mínimos que o sistema precisa.
2. Criar integração. A tela mostra o client_id (cli_...) e o client_secret (cs_...) uma única vez. Entregue ao desenvolvedor por canal seguro.
3. Só para faturar pagamento recebido fora do Cuidaro: em Pagamentos recebidos fora do Cuidaro, a empresa libera a integração e escolhe a conta que recebe as baixas. Vem desligado.

Trocar o segredo derruba na hora todos os tokens emitidos com o anterior. Revogar desliga a integração de forma definitiva.

Primeira chamada

Peça um token (Autenticação) e chame GET /me para confirmar a empresa da credencial.

curl -X GET 'https://cuidaro.com.br/api/v1/me' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $TOKEN"

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

$response = $client->request('GET', 'me', [
    'headers' => ['Accept' => 'application/json', 'Authorization' => 'Bearer '.$token],
    'http_errors' => false,
]);

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

const token = process.env.CUIDARO_TOKEN;

const response = await fetch('https://cuidaro.com.br/api/v1/me', {
  method: 'GET',
  headers: { 'Accept': 'application/json', Authorization: `Bearer ${token}` },
});
const data = response.status === 204 ? null : await response.json();

import os

import requests

token = os.environ["CUIDARO_TOKEN"]

response = requests.request(
    "GET",
    "https://cuidaro.com.br/api/v1/me",
    headers={"Accept": "application/json", "Authorization": f"Bearer {token}"},
    timeout=15,
)
data = response.json() if response.status_code != 204 else None

{
  "data": {
    "integrator": {
      "name": "Loja virtual",
      "client_id": "cli_exemplo",
      "scopes": [
        "services:read",
        "services:write"
      ]
    },
    "token": {
      "scopes": [
        "services:read",
        "services:write"
      ],
      "expires_at": "2026-10-27T15:00:00-03:00"
    },
    "company": {
      "id": 42,
      "name": "Empresa Exemplo Ltda"
    }
  }
}

Checklist antes de colocar no ar

• Fluxo completo testado com a empresa de testes, inclusive cancelamento e webhooks.
• Empresa de testes com ambiente fiscal em Homologação; a empresa real, com o ambiente fiscal de produção.
• Serviços do catálogo com dados fiscais completos (nfse_ready: true em GET /services).
• Clientes enviados com endereço completo e código IBGE de 7 dígitos.
• Integração e endpoint de webhook criados na empresa real; ids descobertos de novo nela.
• Consulta periódica das OS em aberto como rede de segurança dos webhooks.
• Segredos fora do código-fonte e dos logs.