Integrações

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:

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:

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 cobre cada operação, os parâmetros de consulta e os códigos de erro, com uma descrição OpenAPI.

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
// 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.

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.

O Nimbly chama outros sistemas

Uma biblioteca chama serviços externos com as funções auxiliares de HTTP em core/lib/curl.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.