# Agências, equipas e a API

Como as agências anunciam clientes na Agilis com o nome de cada cliente, como funcionam funções, saldos e faturas, e como usar a API REST da Agilis.

**Em resumo:** uma agência regista-se uma única vez, com a sua própria denominação legal, e anuncia pelos seus clientes introduzindo o nome de cada cliente em **Nome apresentado aos membros**. A agência paga, detém os saldos e recebe as faturas. Os Programadores podem criar e gerir Ofertas e Eventos através da **API REST da Agilis** (https://ads.agilis.dating) com chaves de API obtidas no Portal de Anúncios; as chaves de teste são gratuitas e nunca são mostradas aos membros.

## Para agências

1. **Registe a agência** com a sua própria denominação legal. → [Como se registar](https://www.agilis.dating/pt/business/guide/register)
2. Ao criar uma Oferta ou um Evento, introduza o **nome do seu cliente** em **Nome apresentado aos membros**. Os membros veem o nome do cliente, não o seu.
3. Tem de estar autorizado por cada cliente a anunciar em nome dele. Os Termos e Condições de Publicidade atribuem esta responsabilidade à agência.

**Quem paga e quem recebe a fatura**

- O pagamento é feito pela conta da sua agência, na moeda de faturação da agência.
- Cada pessoa da sua agência tem o seu próprio saldo e paga a partir dele. O Saldo da organização é o total. → [Como funcionam os saldos](https://www.agilis.dating/pt/business/guide/pricing)
- As faturas e os resultados ficam em nome da sua agência, com uma fatura por pagamento, para que possa refaturar a cada cliente.
- Para manter separados os gastos de cada cliente, utilize uma Oferta ou um Evento por cliente e refature a partir da respetiva fatura.

## Funções da equipa

Os Administradores da organização e os Anunciantes trabalham no Portal de Anúncios; os Programadores trabalham através da API. Os Programadores não podem criar Ofertas nem Eventos no Portal de Anúncios, mas, com as suas chaves de API, podem criá-los, publicá-los e pagá-los através da API, e a sua empresa é responsável pela forma como as respetivas chaves são utilizadas. A tabela completa está em [Funções e permissões da equipa](https://www.agilis.dating/pt/business/guide/getting-started).

## A API REST da Agilis

- **URL base:** https://ads.agilis.dating
- **Referência:** www.agilis.dating/api-doc, com exemplos em cURL, Python, Node.js e PHP, e um assistente da API
- **Formatos legíveis por máquina:** OpenAPI 3.1 em www.agilis.dating/openapi.json, Markdown em www.agilis.dating/api-doc.md e o texto completo para ferramentas de IA em www.agilis.dating/llms-full.txt
- **Ofertas:** listar as suas categorias e os interesses; calcular o preço de uma Oferta antes de a criar; criar, listar, pausar, retomar e eliminar Ofertas; consultar os resultados de cada Oferta
- **Eventos:** pré-visualizar, publicar, listar, editar, reagendar, cancelar e eliminar Eventos; consultar os resultados de cada Evento

### Obter uma chave de API

1. Inicie sessão no Portal de Anúncios como Administrador da organização ou Programador.
2. Escolha o **Modo de teste** ou o Modo real com o interruptor no topo da página.
3. Aceda a **Chaves de API** → **Criar nova chave**, atribua-lhe um nome e, se pretender, uma data de expiração.
4. **Copie a chave de imediato.** Não a poderá ver novamente.

As chaves de teste começam por `pk_test_`; as chaves reais começam por `pk_live_`. Cada pessoa pode ter até 10 chaves em cada modo. **Renovar chave** substitui uma chave de imediato, por isso atualize primeiro os seus sistemas. Envie a chave no cabeçalho de pedido `x-api-key`: `x-api-key: pk_test_…`.

### Desenvolver em segurança

- Desenvolva e teste com uma chave `pk_test_`: as Ofertas e os Eventos de teste são gratuitos e nunca são mostrados aos membros.
- Calcule o preço de uma Oferta com o endpoint de estimativa de preço antes de a criar.
- Mantenha as chaves fora de repositórios de código e de navegadores; chame a API a partir do seu servidor.

## Perguntas

### Uma agência pode gerir vários clientes a partir de uma só conta?

Sim. Registe a agência uma única vez e indique o cliente em cada Oferta ou Evento.

### Cada cliente pode ter a sua própria fatura?

As faturas são emitidas em nome da sua agência, uma por pagamento. Refature aos seus clientes a partir delas.

### Existe um ambiente de testes?

Sim. O Modo de teste, com chaves `pk_test_`, é um ambiente de testes completo. Nada é cobrado e nada é mostrado aos membros.

### Posso ligar ferramentas de programação com IA?

Sim. Aponte a sua ferramenta para www.agilis.dating/api-doc.md ou www.agilis.dating/openapi.json.

Source: https://www.agilis.dating/pt/business/guide/agencies-and-api