# Integrações

A API REST para outros sistemas, endpoints próprios, webhooks e chamadas de saída.

O Nimbly se conecta com outros sistemas nas duas direções: outros sistemas leem e gravam seus dados pela API REST, e suas bibliotecas chamam serviços externos.

## Outros sistemas chamam o Nimbly

Todo recurso tem uma API REST. Quem chama entra como usuário do Nimbly e recebe um token:

```bash
curl -X POST https://example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "feed@example.com", "password": "…"}'
```

O token vale por 10 minutos e é renovado com um `GET` no mesmo endereço. Toda requisição o envia:

```bash
curl "https://example.com/api/v1/projects?filter=published:1&sort=year|desc&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

Dê a cada integração um usuário próprio e uma função só com as permissões necessárias. Um feed que lê projetos recebe `view-projects`; um sistema que cria pedidos recebe `create-orders`. Um usuário só pode pedir um token quando o acesso à API está ligado para a conta dele. Ligue **API access** no painel de ações do usuário no admin, ao lado do formulário de edição em `/nb-admin/users/<uuid>`; isso exige uma função que possa editar usuários. Ao desligar, o token do usuário para de funcionar na hora. Guarde as credenciais no cofre de segredos do próprio sistema que chama.

A [referência da API REST](/pt/docs/reference/api/) cobre cada operação, os parâmetros de consulta e os códigos de erro, com uma [descrição OpenAPI](/reference/api/openapi.json).

## Endpoints próprios

Quando uma integração precisa de uma resposta que a API de recursos não dá, escreva uma rota com uma biblioteca. Verifique o acesso primeiro, depois responda:

```php
<?php
// ext/lib/order-summary.php

function order_summary_sc($params)
{
    load_library('api');
    if (!api_access('view-orders')) {
        header('Content-Type: application/json', true, 403);
        return json_encode(['message' => 'ACCESS_DENIED']);
    }
    load_library('data');
    $orders = data_query('orders', ['filter' => 'status:open', 'limit' => 100]);
    header('Content-Type: application/json');
    return json_encode(['open' => $orders['total']]);
}
```

O `api_access()` aceita o usuário autenticado, um token e operações públicas permitidas explicitamente, então o endpoint funciona tanto para o navegador quanto para outros sistemas. Veja [O que uma rota devolve](/pt/docs/guides/responses/).

## Webhooks

Um provedor de pagamento ou outro serviço que chama o seu site é uma rota como qualquer outra, por exemplo `ext/uri/webhooks/payments/index.tpl` com uma biblioteca que verifica a assinatura, registra o evento e coloca o passo seguinte na fila como job. Responda rápido e faça o trabalho no job; veja [Trabalho em segundo plano](/pt/docs/guides/jobs/).

## O Nimbly chama outros sistemas

Uma biblioteca chama serviços externos com as funções auxiliares de HTTP em `core/lib/curl.php`:

```php
load_library('curl');
load_library('env');
$rates = curl_get('https://api.example.com/rates', ['Authorization: Bearer ' . env('RATES_API_KEY')]);
```

Guarde as chaves no `.env` e leia-as com `env()`. Chamadas que podem ser lentas, falhar ou precisar ser repetidas pertencem a um job, não a uma requisição de página.

## Mantenha num módulo

Uma integração com rotas, bibliotecas e dados próprios, como um provedor de pagamento com página de checkout e webhook, fica mais fácil de manter e reutilizar como [módulo](/pt/docs/concepts/modules/).