O token da Deel de que o Odoo precisa
A Deel distingue três tokens: o de organização, que representa toda a organização; o pessoal, que representa um utilizador; e o de trabalhador, que representa um trabalhador em EOR. O conector trabalha com o de organização, que vem marcado em Método de Autenticação: Token da Organização. Segundo o centro de ajuda da Deel, um token pessoal expira se quem o criou sair da empresa, e um de organização não depende de ninguém e não expira, embora não sirva para assinar contratos. Para o criar é preciso ser Org Admin ou IT Developer Admin na Deel.
Passo a passo no Developer Center da Deel
- Entre no Developer Center. O guia de autenticação da Deel chega lá por More e depois Developer; o guia de webhooks, pelo ícone do perfil, Settings e Developer Center; e o centro de ajuda, por Apps & Integrations.
- Abra o separador Access Tokens e carregue em Generate new token.
- Escolha o tipo Organization token.
- Marque as permissões da tabela abaixo e decida a que dados sensíveis o token poderá chegar.
- Carregue em Generate e copie o token nesse momento: a Deel avisa que depois não o volta a mostrar.
A Deel dá chaves diferentes para o seu sandbox e para produção, e pede que não se misturem. No Odoo, o campo Ambiente da ligação oferece Produção e Ambiente de Teste (sandbox), que é uma organização de demonstração da Deel (demo.deel.com) sem dinheiro real. O token tem de ser do ambiente que escolher.
Que permissões marcar
A Deel chama às suas permissões recurso:read e recurso:write, e a sua referência indica a que cada chamada pede. Estas são, entre outras, as chamadas que o conector faz e a permissão de cada uma segundo a referência da Deel de 18-11-2026:
| Para quê | Chamada | Permissão |
|---|---|---|
Testar conexão | GET /organizations | organizations:read |
| Entidades legais | GET /legal-entities | organizations:read, accounting:read |
| Contratos e pessoas | GET /contracts, GET /people | contracts:read, people:read |
| Faturas, comissões da Deel e os seus PDF | GET /invoices, GET /invoices/deel, GET /invoices/{id}/download | accounting:read |
| Pagamentos e o seu detalhe | GET /payments, GET /payments/{payment_id}/breakdown | accounting:read |
| Ciclos salariais e centros de custo | GET /legal-entities/{legal_entity_id}/payroll-events, GET /legal-entities/{legal_entity_id}/cost-centers | legal-entity:read |
| Relatório bruto-líquido de cada ciclo | GET /reports/payroll/cycles/{cycle_id}/gross-to-net | payslips:read |
| Criar e remover o webhook | POST /webhooks, DELETE /webhooks/{id} | webhooks:write |
| Enviar à Deel os centros de custo | POST /legal-entities/{legal_entity_id}/cost-centers/synchronize | legal-entity:write |
As duas últimas linhas escrevem na Deel. O webhook só é criado se um administrador carregar em Registar webhook, e os centros de custo só vão para a Deel se escolher que é o Odoo a geri-los; por omissão, vão da Deel para o Odoo. A ajuda do campo do token pede permissões de leitura. Só com essas, segundo a sua referência, a Deel recusará a criação do webhook e, se escolher que o Odoo gere os centros de custo, também o seu envio. O guia de autenticação da Deel dá duas respostas possíveis para um token a que falta uma permissão: 403 ou 401. Com um 403, a sincronização a cada 30 minutos continua a ler todo o resto. Com um 401, o conector trata-o como um token recusado e, se o Odoo gerir os centros de custo, cada passagem para aí, antes dos contratos, das faturas, dos pagamentos e dos ciclos salariais; nesse caso, o token precisa também de legal-entity:write. Se a Deel mudar a permissão de alguma chamada, vale a sua referência.
Onde se cola no Odoo
Na ligação da Deel, um administrador:
- marca
Aceito que o FlexigoTech Cloud mantenha a credencial do Deel, porque até lá o campo do token não deixa escrever e nada é enviado; - deixa
Token da OrganizaçãoemMétodo de Autenticaçãoe escolhe oAmbiente; - cola o token em
Token de Organização Deele guarda.
Ao guardar, o conector envia o token para a FlexigoTech Cloud, que tem de estar em teste ou subscrita, e regista a data em Credencial guardada em. O campo volta a aparecer vazio, e de propósito: é só de escrita e o Odoo não fica com o token. Só um administrador o pode guardar. Depois, Testar conexão pede à Deel a organização e as suas entidades legais e responde com o nome e quantas são.

Se mudar o Ambiente ou o Método de Autenticação de uma ligação já guardada, a credencial guardada deixa de valer: a ligação volta a Não conectado, é preciso colar o token outra vez e a entrada antiga é apagada da FlexigoTech Cloud.
Para onde vai o token
Segundo o próprio módulo, a FlexigoTech Cloud guarda o token cifrado, uma entrada por ligação, e põe-no em cada chamada à Deel como cabeçalho Authorization: Bearer, que é como a Deel pede que se use. As chamadas à Deel não saem diretamente do seu Odoo; a única coisa que vai no sentido contrário são os avisos dos webhooks, que a Deel envia para o seu Odoo e que estão explicados em os webhooks da Deel com o Odoo. Desconectar apaga o token da FlexigoTech Cloud e, se o serviço estiver ativo, o webhook da Deel, e não toca em nada do que já foi sincronizado.

A Deel recomenda guardar as credenciais num cofre seguro e nunca no código, trocar os tokens a cada trimestre ou quando alguém sai da equipa, e apagar os que não se usam. Com o conector, trocar é criar o token novo na Deel, colá-lo no mesmo campo, guardar e apagar o antigo na Deel.
Autorizar com o Deel, hoje
A outra opção de Método de Autenticação, Autorizar com o Deel, liga sem copiar nenhum token: um administrador da Deel aprova a app da FlexigoTech. Enquanto a FlexigoTech Cloud não tiver essa app para o ambiente escolhido, o conector responde «Autorizar com o Deel ainda não está disponível para este ambiente do Deel. Entretanto, use um token da organização: nada foi enviado ao Deel.»
Os limites e os erros
A Deel admite 5 pedidos por segundo por organização, somando todos os seus tokens, numa janela móvel de 1 segundo, e o seu sandbox tem os mesmos limites. Acima disso responde 429 e, segundo a sua documentação, não envia cabeçalhos que avisem antes. Se outro programa ler a mesma organização, partilha esses 5 com o conector. A sincronização deixa pelo menos 0,25 segundos entre uma chamada e a seguinte; perante um 429 espera (um segundo, salvo se a resposta pedir outra espera, e nunca mais de 5), repete até 3 vezes e, se continuar, deixa a chamada para a passagem seguinte.
| Resposta da Deel | Causa, segundo a Deel | O que faz o conector |
|---|---|---|
| 401 | Token inválido ou expirado, sem o cabeçalho Authorization ou sem as permissões necessárias | Passa a ligação para O Deel recusou o token e pede para guardar um novo |
| 403 | Falta ao token a permissão dessa chamada | Não dá o token como mau: mostra o motivo que a Deel indica |
| 429 | Mais de 5 pedidos por segundo na organização | Espera e repete |
Uma nota do código do conector acrescenta outro 403, o «Error 1010»: é o Cloudflare da Deel a bloquear o User-Agent do Python-urllib, e por isso o conector envia sempre o seu. Para ver porque a Deel recusou uma chamada, os Request logs do Developer Center guardam 15 dias de pedidos feitos com os tokens da organização, também os recusados, com o motivo.
O que foi testado
O conector funciona no Odoo 17, 18, 19 e 20, num servidor próprio ou no Odoo.sh, e não no Odoo Online. Foi testado de ponta a ponta contra uma organização de demonstração da Deel (demo.deel.com), através da FlexigoTech Cloud: a ligação, as entidades legais, um contrato com a sua pessoa e o seu fornecedor, os webhooks e uma segunda passagem sem duplicados. Faturas, pagamentos e ciclos salariais foram testados com respostas construídas sobre a referência da API da Deel, porque essa organização ainda não tinha. O que entra depois como fatura de fornecedor está no guia da Deel invoice, e a comparação com as integrações da Deel, em Deel integrations. O conector está explicado por inteiro na sua página e publicado na Odoo Apps.
Continue a ler
Verificado no código do conector (versão 20.0) e nas fontes indicadas
Fontes
- developer.deel.com/api/authentication
- help.letsdeel.com/hc/en-gb/articles/8801712601233-How-To-Use-Deel-API
- developer.deel.com/api/webhooks/no-code
- help.letsdeel.com/hc/en-gb/articles/10660690287761-How-To-Create-And-Manage-Webhooks-Notif
- developer.deel.com/api/sandbox
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_account.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_cost_center.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_legal_entity.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_contract.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_payment.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_payroll.py
- developer.deel.com/api/rate-limits
- developer.deel.com/api/endpoints/organizations/get-organizations
- developer.deel.com/api/endpoints/legal-entities/get-legal-entities
- developer.deel.com/api/endpoints/contracts/get-contracts
- developer.deel.com/api/hris-endpoints/people/get-people
- developer.deel.com/api/reference/endpoints/accounting/retrieve-deel-invoices-v-2026-01-01
- developer.deel.com/api/reference/endpoints/accounting/get-billing-invoice-download-link-v-
- developer.deel.com/api/reference/endpoints/accounting/retrieve-payment-receipts-v-2027-01-
- developer.deel.com/api/reference/endpoints/accounting/retrieve-a-payment-breakdown-v-2026-
- developer.deel.com/api/reference/endpoints/list-cycles/list-payroll-cycles-v-2026-01-01
- developer.deel.com/api/reference/endpoints/reports/gets-g-2-n-report-data-for-a-given-payr
- developer.deel.com/api/endpoints/cost-centers/get-legal-entity-cost-centers
- developer.deel.com/api/reference/endpoints/cost-centers/sync-cost-centers-for-legal-entity
- developer.deel.com/api/endpoints/webhooks/create-webhook
- developer.deel.com/api/endpoints/webhooks/delete-webhook
- developer.deel.com/api/reference/endpoints/accounting/retrieve-invoices-v-2026-01-01
- Código do módulo: flexigo_deel_connector 20.0 (18442307): models/deel_invoice.py
- Código do módulo: flexigo_deel_connector 20.0 (18442307): data/deel_cron.xml
- apps.odoo.com/apps/modules/20.0/flexigo_deel_connector
- Código do módulo: flexigo_deel_connector 20.0 (18442307): views/deel_account_views.xml
