Começar

Início rápido

Da chave de API à primeira pré-autorização e ao primeiro webhook verificado.

Gere uma chave de API

Na plataforma, abra Minha empresa › Integração e clique em Nova chave. Preencha:
- Nome — para reconhecer a chave depois, como ERP Financeiro.
- Usuário responsável — as operações saem em nome dele. Precisa ter permissão de solicitar e pré-autorizar antecipações; quem não tem aparece desabilitado na lista.
- Escopos — marque Criar e cancelar pré-autorizações. Pelo menos um escopo é obrigatório.
- Validade — 30, 90, 180, 365 dias (padrão 365).
A chave começa com oneos_sk_ e aparece uma única vez.
Guarde a chave fora do código

Use o cofre de segredos do seu ambiente, ou uma variável de ambiente:
shell
```
export ONEOS_API_KEY="oneos_sk_..."
```

Crie a primeira pré-autorização

Envie o fornecedor e a nota. A Idempotency-Key é opcional, mas recomendada: derive-a da nota no seu ERP, e uma retentativa nunca cria duas operações.

POST /pre-authorizations

curl -X POST https://app.oneos.com.br/api/integration/v1/pre-authorizations \
  -H "Authorization: Bearer $ONEOS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: PED-4581-nf-48211" \
  -d '{
    "supplier": { "cnpj": "11.222.333/0001-81", "email": "financeiro@fornecedor.com.br" },
    "invoice": { "amount": 18400, "dueDate": "2026-11-30", "number": "48211" },
    "externalReference": "PED-4581"
  }'

const response = await fetch('https://app.oneos.com.br/api/integration/v1/pre-authorizations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ONEOS_API_KEY}`,
    'Content-Type': 'application/json',
    // mesma chave em toda retentativa desta nota
    'Idempotency-Key': 'PED-4581-nf-48211',
  },
  body: JSON.stringify({
    supplier: { cnpj: '11.222.333/0001-81', email: 'financeiro@fornecedor.com.br' },
    invoice: { amount: 18400, dueDate: '2026-11-30', number: '48211' },
    externalReference: 'PED-4581',
  }),
})

if (!response.ok) {
  const { errors } = await response.json()
  throw new Error(errors.map((e) => `${e.code}: ${e.message}`).join('; '))
}

const preAuthorization = await response.json()
console.log(preAuthorization.id, preAuthorization.status) // 48213 'IN_PRE_AUTH'

import os
import requests

response = requests.post(
    "https://app.oneos.com.br/api/integration/v1/pre-authorizations",
    headers={
        "Authorization": f"Bearer {os.environ['ONEOS_API_KEY']}",
        # mesma chave em toda retentativa desta nota
        "Idempotency-Key": "PED-4581-nf-48211",
    },
    json={
        "supplier": {"cnpj": "11.222.333/0001-81", "email": "financeiro@fornecedor.com.br"},
        "invoice": {"amount": 18400, "dueDate": "2026-11-30", "number": "48211"},
        "externalReference": "PED-4581",
    },
    timeout=30,
)

if not response.ok:
    errors = response.json()["errors"]
    raise RuntimeError("; ".join(f"{e['code']}: {e['message']}" for e in errors))

pre_authorization = response.json()
print(pre_authorization["id"], pre_authorization["status"])  # 48213 IN_PRE_AUTH

<?php
$ch = curl_init('https://app.oneos.com.br/api/integration/v1/pre-authorizations');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ONEOS_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: PED-4581-nf-48211',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'supplier' => ['cnpj' => '11.222.333/0001-81', 'email' => 'financeiro@fornecedor.com.br'],
        'invoice' => ['amount' => 18400, 'dueDate' => '2026-11-30', 'number' => '48211'],
        'externalReference' => 'PED-4581',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status >= 400) {
    $messages = array_map(fn ($e) => "{$e['code']}: {$e['message']}", $body['errors']);
    throw new RuntimeException(implode('; ', $messages));
}

echo $body['id'], ' ', $body['status']; // 48213 IN_PRE_AUTH

A resposta 201 traz a operação criada. Guarde o id:

201 Created

{
  "id": 48213,
  "status": "IN_PRE_AUTH",
  "externalReference": "PED-4581",
  "payer": {
    "cnpj": "44555666000199",
    "name": "Construtora Exemplo LTDA"
  },
  "supplier": {
    "cnpj": "11222333000181",
    "name": "Fornecedor Exemplo ME"
  },
  "invoice": {
    "amount": 18400,
    "dueDate": "2026-11-30",
    "number": "48211",
    "withheldTaxAmount": 0
  },
  "expiresAt": "2026-09-19T02:59:59.000Z",
  "createdAt": "2026-09-15T13:00:00.000Z"
}

Configure o webhook

Em Minha empresa › Webhooks, informe a URL do seu endpoint (HTTPS, porta 443), escolha os eventos e guarde o signing secret (whsec_…), que também aparece uma única vez.
Verifique a assinatura e responda rápido

Toda entrega traz o header x-oneos-signature. Confira o HMAC antes de confiar no corpo e responda 2xx em até 10 segundos. O passo a passo, com código e um verificador interativo, está em Verificar assinatura.
Teste o fluxo de ponta a ponta

Na tela de webhooks, use Enviar evento de teste: chega um webhook.test assinado de verdade. Na aba Entregas você vê o status, as tentativas e o corpo de cada envio.

Gere uma chave de API

Guarde a chave fora do código

Crie a primeira pré-autorização

Configure o webhook

Verifique a assinatura e responda rápido

Teste o fluxo de ponta a ponta

Próximos passos