# Protocolsio Integration > Integração com a API protocols.io para gerenciar protocolos científicos. Esta skill deve ser usada ao trabalhar com protocols.io para pesquisar, criar, atualizar ou publicar protocolos; gerenciar etapas e materiais de protocolo; lidar com discussões e comentários; organizar espaços de trabalho; fazer upload e gerenciar arquivos; ou integrar funcionalidade protocols.io em workflows. Aplicável para descoberta de protocolo, desenvolvimento colaborativo de protocolo, rastreamento de experimentos, gerenciamento de protocolo de laboratório e documentação científica. - Skill: `artubss/protocolsio-integration` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add artubss/protocolsio-integration` - Raw SKILL.md: https://api.skillmd.com/api/skills/artubss/protocolsio-integration/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: artubss (https://skillmd.com/u/artubss) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/artubss/protocolsio-integration --- # Integração Protocols.io ## Visão Geral Protocols.io é uma plataforma abrangente para desenvolver, compartilhar e gerenciar protocolos científicos. Esta skill oferece integração completa com a API v3 protocols.io, permitindo acesso programático a protocolos, espaços de trabalho, discussões, gerenciamento de arquivos e recursos de colaboração. ## Quando Usar Esta Skill Use esta skill ao trabalhar com protocols.io em qualquer um dos seguintes cenários: - **Descoberta de Protocolo**: Pesquisar protocolos existentes por palavras-chave, DOI ou categoria - **Gerenciamento de Protocolo**: Criar, atualizar ou publicar protocolos científicos - **Gerenciamento de Etapas**: Adicionar, editar ou organizar etapas e procedimentos de protocolo - **Desenvolvimento Colaborativo**: Trabalhar com membros da equipe em protocolos compartilhados - **Organização do Espaço de Trabalho**: Gerenciar repositórios de protocolo de laboratório ou institucionais - **Discussão e Feedback**: Adicionar ou responder comentários de protocolo - **Gerenciamento de Arquivos**: Fazer upload de arquivos de dados, imagens ou documentos para protocolos - **Rastreamento de Experimentos**: Documentar execuções de protocolo e resultados - **Exportação de Dados**: Fazer backup ou migrar coleções de protocolo - **Projetos de Integração**: Criar ferramentas que interagem com protocols.io ## Capacidades Principais Esta skill oferece orientação abrangente em cinco áreas principais de capacidade: ### 1. Autenticação e Acesso Gerenciar autenticação de API usando tokens de acesso e fluxos OAuth. Inclui tanto tokens de acesso do cliente (para conteúdo pessoal) quanto tokens OAuth (para aplicações multi-usuário). **Operações principais:** - Gerar links de autorização para fluxo OAuth - Trocar códigos de autorização por tokens de acesso - Renovar tokens expirados - Gerenciar limites de taxa e permissões **Referência:** Leia `references/authentication.md` para procedimentos detalhados de autenticação, implementação OAuth e melhores práticas de segurança. ### 2. Operações de Protocolo Gerenciamento completo do ciclo de vida de protocolo, desde criação até publicação. **Operações principais:** - Pesquisar e descobrir protocolos por palavras-chave, filtros ou DOI - Recuperar informações detalhadas de protocolo com todas as etapas - Criar novos protocolos com metadados e tags - Atualizar informações e configurações de protocolo - Gerenciar etapas de protocolo (criar, atualizar, deletar, reordenar) - Tratar materiais e reagentes de protocolo - Publicar protocolos com emissão de DOI - Marcar protocolos para acesso rápido - Gerar PDFs de protocolo **Referência:** Leia `references/protocols_api.md` para orientação abrangente sobre gerenciamento de protocolo, incluindo endpoints da API, parâmetros, workflows comuns e exemplos. ### 3. Discussões e Colaboração Habilitar engajamento comunitário através de comentários e discussões. **Operações principais:** - Visualizar comentários no nível de protocolo e etapa - Criar novos comentários e respostas encadeadas - Editar ou deletar seus próprios comentários - Analisar padrões de discussão e feedback - Responder a perguntas e problemas de usuários **Referência:** Leia `references/discussions.md` para gerenciamento de discussão, encadeamento de comentários e workflows de colaboração. ### 4. Gerenciamento de Espaço de Trabalho Organizar protocolos dentro de espaços de trabalho de equipe com permissões baseadas em funções. **Operações principais:** - Listar e acessar espaços de trabalho do usuário - Recuperar detalhes do espaço de trabalho e listas de membros - Solicitar acesso ou ingressar em espaços de trabalho - Listar protocolos específicos do espaço de trabalho - Criar protocolos dentro de espaços de trabalho - Gerenciar permissões e colaboração do espaço de trabalho **Referência:** Leia `references/workspaces.md` para organização do espaço de trabalho, gerenciamento de permissões e padrões de colaboração em equipe. ### 5. Operações de Arquivo Upload, organização e gerenciamento de arquivos associados a protocolos. **Operações principais:** - Pesquisar arquivos e pastas do espaço de trabalho - Fazer upload de arquivos com metadados e tags - Baixar arquivos e verificar uploads - Organizar arquivos em hierarquias de pasta - Atualizar metadados de arquivo - Deletar e restaurar arquivos - Gerenciar armazenamento e organização **Referência:** Leia `references/file_manager.md` para procedimentos de upload de arquivo, estratégias de organização e gerenciamento de armazenamento. ### 6. Funcionalidades Adicionais Funcionalidade complementar incluindo perfis, notificações e exportações. **Operações principais:** - Gerenciar perfis e configurações de usuário - Consultar protocolos publicados recentemente - Criar e rastrear registros de experimento - Receber e gerenciar notificações - Exportar dados da organização para arquivo **Referência:** Leia `references/additional_features.md` para gerenciamento de perfil, descoberta de publicação, rastreamento de experimento e exportação de dados. ## Começando ### Passo 1: Configuração de Autenticação Antes de usar qualquer funcionalidade da API protocols.io: 1. Obter um token de acesso (CLIENT_ACCESS_TOKEN ou OAUTH_ACCESS_TOKEN) 2. Ler `references/authentication.md` para procedimentos detalhados de autenticação 3. Armazenar o token com segurança 4. Incluir em todas as solicitações como: `Authorization: Bearer YOUR_TOKEN` ### Passo 2: Identificar Seu Caso de Uso Determine qual área de capacidade atende suas necessidades: - **Trabalhando com protocolos?** → Leia `references/protocols_api.md` - **Gerenciando protocolos de equipe?** → Leia `references/workspaces.md` - **Tratando comentários/feedback?** → Leia `references/discussions.md` - **Fazendo upload de arquivos/dados?** → Leia `references/file_manager.md` - **Rastreando experimentos ou perfis?** → Leia `references/additional_features.md` ### Passo 3: Implementar Integração Siga a orientação nos arquivos de referência relevantes: - Cada referência inclui documentação detalhada de endpoint - Parâmetros de API e formatos de solicitação/resposta são especificados - Casos de uso comuns e workflows são fornecidos com exemplos - Orientação de melhores práticas e tratamento de erros incluída ## URL Base e Formato de Solicitação Todas as solicitações de API usam a URL base: ``` https://protocols.io/api/v3 ``` Todas as solicitações requerem o cabeçalho Authorization: ``` Authorization: Bearer YOUR_ACCESS_TOKEN ``` A maioria dos endpoints suporta formato de solicitação/resposta JSON com `Content-Type: application/json`. ## Opções de Formato de Conteúdo Muitos endpoints suportam um parâmetro `content_format` para controlar como o conteúdo do protocolo é retornado: - `json`: Formato Draft.js JSON (padrão) - `html`: Formato HTML - `markdown`: Formato Markdown Incluir como parâmetro de query: `?content_format=html` ## Limite de Taxa Esteja ciente dos limites de taxa da API: - **Endpoints padrão**: 100 solicitações por minuto por usuário - **Endpoint de PDF**: 5 solicitações/minuto (conectado), 3 solicitações/minuto (não conectado) Implementar backoff exponencial para erros de limite de taxa (HTTP 429). ## Workflows Comuns ### Workflow 1: Importar e Analisar Protocolo Para analisar um protocolo existente de protocols.io: 1. **Pesquisar**: Use `GET /protocols` com palavras-chave para encontrar protocolos relevantes 2. **Recuperar**: Obter detalhes completos com `GET /protocols/{protocol_id}` 3. **Extrair**: Analisar etapas, materiais e metadados para análise 4. **Revisar discussões**: Verificar `GET /protocols/{id}/comments` para feedback de usuários 5. **Exportar**: Gerar PDF se necessário para referência offline **Arquivos de referência**: `protocols_api.md`, `discussions.md` ### Workflow 2: Criar e Publicar Protocolo Para criar um novo protocolo e publicar com DOI: 1. **Autenticar**: Garantir que você tenha token de acesso válido (ver `authentication.md`) 2. **Criar**: Use `POST /protocols` com título e descrição 3. **Adicionar etapas**: Para cada etapa, use `POST /protocols/{id}/steps` 4. **Adicionar materiais**: Documentar reagentes em componentes de etapa 5. **Revisar**: Verificar se todo conteúdo está completo e preciso 6. **Publicar**: Emitir DOI com `POST /protocols/{id}/publish` **Arquivos de referência**: `protocols_api.md`, `authentication.md` ### Workflow 3: Espaço de Trabalho de Laboratório Colaborativo Para configurar gerenciamento de protocolo de equipe: 1. **Criar/ingressar no espaço de trabalho**: Acessar ou solicitar associação ao espaço de trabalho (ver `workspaces.md`) 2. **Organizar estrutura**: Criar hierarquia de pasta para protocolos de laboratório (ver `file_manager.md`) 3. **Criar protocolos**: Use `POST /workspaces/{id}/protocols` para protocolos de equipe 4. **Fazer upload de arquivos**: Adicionar dados experimentais e imagens 5. **Habilitar discussões**: Membros da equipe podem comentar e fornecer feedback 6. **Rastrear experimentos**: Documentar execuções de protocolo com registros de experimento **Arquivos de referência**: `workspaces.md`, `file_manager.md`, `protocols_api.md`, `discussions.md`, `additional_features.md` ### Workflow 4: Documentação de Experimento Para rastrear execuções de protocolo e resultados: 1. **Executar protocolo**: Realizar protocolo em laboratório 2. **Fazer upload de dados**: Use File Manager API para fazer upload de resultados (ver `file_manager.md`) 3. **Criar registro**: Documentar execução com `POST /protocols/{id}/runs` 4. **Vincular arquivos**: Referenciar arquivos de dados enviados em registro de experimento 5. **Anotar modificações**: Documentar quaisquer desvios ou otimizações de protocolo 6. **Analisar**: Revisar múltiplas execuções para avaliação de reprodutibilidade **Arquivos de referência**: `additional_features.md`, `file_manager.md`, `protocols_api.md` ### Workflow 5: Descoberta e Citação de Protocolo Para encontrar e citar protocolos em pesquisa: 1. **Pesquisar**: Consultar protocolos publicados com `GET /publications` 2. **Filtrar**: Usar filtros de categoria e palavra-chave para protocolos relevantes 3. **Revisar**: Ler detalhes de protocolo e comentários da comunidade 4. **Marcar**: Salvar protocolos úteis com `POST /protocols/{id}/bookmarks` 5. **Citar**: Usar DOI de protocolo em publicações (atribuição apropriada) 6. **Exportar PDF**: Gerar PDF formatado para referência offline **Arquivos de referência**: `protocols_api.md`, `additional_features.md` ## Exemplos de Solicitações Python ### Pesquisa Básica de Protocolo ```python import requests token = "YOUR_ACCESS_TOKEN" headers = {"Authorization": f"Bearer {token}"} # Pesquisar protocolos CRISPR response = requests.get( "https://protocols.io/api/v3/protocols", headers=headers, params={ "filter": "public", "key": "CRISPR", "page_size": 10, "content_format": "html" } ) protocols = response.json() for protocol in protocols["items"]: print(f"{protocol['title']} - {protocol['doi']}") ``` ### Criar Novo Protocolo ```python import requests token = "YOUR_ACCESS_TOKEN" headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json" } # Criar protocolo data = { "title": "CRISPR-Cas9 Gene Editing Protocol", "description": "Comprehensive protocol for CRISPR gene editing", "tags": ["CRISPR", "gene editing", "molecular biology"] } response = requests.post( "https://protocols.io/api/v3/protocols", headers=headers, json=data ) protocol_id = response.json()["item"]["id"] print(f"Created protocol: {protocol_id}") ``` ### Fazer Upload de Arquivo para Espaço de Trabalho ```python import requests token = "YOUR_ACCESS_TOKEN" headers = {"Authorization": f"Bearer {token}"} # Fazer upload de arquivo with open("data.csv", "rb") as f: files = {"file": f} data = { "folder_id": "root", "description": "Experimental results", "tags": "experiment,data,2025" } response = requests.post( "https://protocols.io/api/v3/workspaces/12345/files/upload", headers=headers, files=files, data=data ) file_id = response.json()["item"]["id"] print(f"Uploaded file: {file_id}") ``` ## Tratamento de Erros Implementar tratamento robusto de erros para solicitações de API: ```python import requests import time def make_request_with_retry(url, headers, max_retries=3): for attempt in range(max_retries): try: response = requests.get(url, headers=headers) if response.status_code == 200: return response.json() elif response.status_code == 429: # Rate limit retry_after = int(response.headers.get('Retry-After', 60)) time.sleep(retry_after) continue elif response.status_code >= 500: # Server error time.sleep(2 ** attempt) # Exponential backoff continue else: response.raise_for_status() except requests.exceptions.RequestException as e: if attempt == max_retries - 1: raise time.sleep(2 ** attempt) raise Exception("Max retries exceeded") ``` ## Arquivos de Referência Carregue o arquivo de referência apropriado baseado em sua tarefa: - **`authentication.md`**: Fluxos OAuth, gerenciamento de token, limite de taxa - **`protocols_api.md`**: CRUD de protocolo, etapas, materiais, publicação, PDFs - **`discussions.md`**: Comentários, respostas, colaboração - **`workspaces.md`**: Espaços de trabalho de equipe, permissões, organização - **`file_manager.md`**: Upload de arquivo, pastas, gerenciamento de armazenamento - **`additional_features.md`**: Perfis, publicações, experimentos, notificações Para carregar um arquivo de referência, leia o arquivo do diretório `references/` quando necessário para funcionalidade específica. ## Melhores Práticas 1. **Autenticação**: Armazenar tokens com segurança, nunca em código ou controle de versão 2. **Limite de Taxa**: Implementar backoff exponencial e respeitar limites de taxa 3. **Tratamento de Erros**: Lidar com todos os códigos de erro HTTP apropriadamente 4. **Validação de Dados**: Validar entrada antes de chamadas de API 5. **Documentação**: Documentar etapas de protocolo completamente 6. **Colaboração**: Usar comentários e discussões para comunicação de equipe 7. **Organização**: Manter convenções de nomenclatura e tagging consistentes 8. **Versionamento**: Rastrear versões de protocolo ao fazer atualizações 9. **Atribuição**: Citar protocolo apropriadamente usando DOIs 10. **Backup**: Exportar regularmente protocolos importantes e dados de espaço de trabalho ## Recursos Adicionais - **Documentação Oficial da API**: https://apidoc.protocols.io/ - **Plataforma Protocols.io**: https://www.protocols.io/ - **Suporte**: Contacte o suporte protocols.io para acesso à API e problemas técnicos - **Comunidade**: Engajar com a comunidade protocols.io para melhores práticas ## Solução de Problemas **Problemas de Autenticação:** - Verificar se o token é válido e não expirou - Verificar formato do cabeçalho Authorization: `Bearer YOUR_TOKEN` - Garantir tipo de token apropriado (CLIENT vs OAUTH) **Limite de Taxa:** - Implementar backoff exponencial para erros 429 - Monitorar frequência de solicitações - Considerar cache para solicitações frequentes **Erros de Permissão:** - Verificar permissões de acesso de espaço de trabalho/protocolo - Verificar função de usuário no espaço de trabalho - Garantir que protocolo não seja privado se acessando sem permissão **Falhas de Upload de Arquivo:** - Verificar tamanho do arquivo contra limites do espaço de trabalho - Verificar se tipo de arquivo é suportado - Garantir que codificação multipart/form-data está correta Para orientação detalhada de solução de problemas, consulte os arquivos de referência específicos cobrindo cada área de capacidade.