Scoutello API
Scoutello API என்பது ஒரு நிறுவனத்தின் தொடர்புகள், பணிகள், நெறிமுறைகள், வாய்ப்புகள், திட்டங்கள், மைல்கற்கள் மற்றும் நிகழ்வுகளை இருதிசைகளிலும் ஒத்திசைக்கும் server-to-server API ஆகும். வெளிச்செல்லும் அஞ்சல் வரலாற்றை மட்டும் வாசிக்கும் வசதி, ஒதுக்கக்கூடிய உறுப்பினர்களைத் தேடும் வசதி, மேலும் entity-aware குறிச்சொற்களைக் கண்டறியும் வசதியும் இதில் உள்ளன. Incremental GET/list வழித்தடங்களும் idempotent batch upsert-களும் இந்தப் பதிப்பின் ஒத்திசைவு அடிப்படைச் செயல்முறைகளாகும். நீக்குதல் செயல்பாடுகள் அல்லது webhooks இதில் இல்லை.
API-யின் அடிப்படை URL:
https://admin.scoutello.com/api/v1
இது Organization settings → Developer/API என்பதிலும் காட்டப்படும். OpenAPI ஆவணம் இங்கே கிடைக்கும்:
https://admin.scoutello.com/api/v1/openapi.json
விசையை உருவாக்கி பாதுகாப்பது
மாட்யூலர் நிறுவனங்களுக்கு, விசைக்குத் தேவையான scopes-களுடன் CRM module-மும் செயலில் இருக்க வேண்டும். செல்லுபடியாகும் விசை, இல்லாத module-ஐச் செயல்படுத்த முடியாது. CRM அணுகல் கிடைக்காதபோது, கோடு module_not_active உடன் HTTP 403 பதில்கள் திரும்பும். நிறுவன நிர்வாகத்தினர் Subscription-இல் CRM-ஐ மதிப்பாய்வு செய்யலாம் அல்லது செயல்படுத்தலாம்; அணுகல் செயல்பாட்டில் வந்த பிறகு மீண்டும் முயற்சிக்கவும்.
நிறுவன நிர்வாகத்தினர் Organization settings → Developer/API என்பதில் integration மற்றும் API key-ஐ உருவாக்கலாம். முழு விசை ஒருமுறை மட்டுமே காட்டப்படும். உரையாடல் பெட்டியை மூடும் முன் அதை secret manager-ல் நகலெடுக்கவும்; Scoutello முழு விசையை மீண்டும் காட்ட முடியாது.
- ஒவ்வொரு வெளிப்புற அமைப்பு மற்றும் சூழலுக்கும் தனித்தனி integration மற்றும் விசையைப் பயன்படுத்தவும்.
- அந்த அமைப்புக்குத் தேவையான scopes-களை மட்டுமே வழங்கவும்.
- விசையை உலாவிக் குறியீடு, URL, source control, பதிவுகள், ஆதரவு செய்திகளில் அல்லது client-side சேமிப்பகத்தில் ஒருபோதும் வைக்க வேண்டாம்.
- விசைகளைத் திட்டமிட்ட இடைவெளிகளில் மாற்றவும். செயலில் உள்ள integration-ன் விசை மாற்றப்படும்போது, மாற்று விசை உடனடியாகச் செயல்படும்; வெளிப்புற அமைப்பு இடையூறு இல்லாமல் மாறுவதற்காக முந்தைய விசை அதிகபட்சம் 15 நிமிடங்கள் மட்டுமே செல்லுபடியாகும். ஏற்கனவே உள்ள முந்தைய காலாவதி விதி தொடரும் என்பதால், முந்தைய விசை அதற்கு முன்பே செயலிழக்கலாம்.
- விசை வெளிப்பட்டிருக்கலாம் எனத் தோன்றினால், மாற்றுவதற்கு முன் integration-ஐ இடைநிறுத்தவும். இடைநிறுத்தம், அந்த integration-ன் அனைத்து விசைகளையும் தற்காலிகமாக நிராகரிக்கும். இடைநிறுத்தப்பட்ட நிலையில் மாற்றினால் overlap இருக்காது: முந்தைய விசை முடக்கப்பட்டே இருக்கும்; integration மீண்டும் தொடங்கப்படும் வரை மாற்று விசையும் முடக்கப்பட்டே இருக்கும்.
- வெளிப்புற அமைப்பின் இணைப்பைத் துண்டிக்கும்போது, முழு integration-ஐ நிரந்தரமாக revoke செய்யவும். Revoke செய்வது அதன் அனைத்து விசைகளையும் முடக்கிவிடும்; இதை மீட்டெடுக்க முடியாது.
ஒவ்வொரு அங்கீகரிக்கப்பட்ட கோரிக்கையிலும் விசையை அனுப்பவும்:
Authorization: Bearer YOUR_API_KEY
Bearer authentication பரிந்துரைக்கப்படுகிறது. Authorization-ஐ அமைக்க முடியாத clients, அதற்குப் பதிலாக x-api-key-ஐப் பயன்படுத்தலாம். இரு headers-ஐயும் அனுப்ப வேண்டாம்; இரு headers-லுள்ள மதிப்புகள் வேறுபட்டால், கோரிக்கைகள் நிராகரிக்கப்படும்.
API backend clients-க்காக வடிவமைக்கப்பட்டுள்ளது; cross-origin உலாவி அணுகலை இது அனுமதிக்காது.
ஒரு விசையை அமைத்த பிறகு GET /whoami-ஐப் பயன்படுத்தி, பயனர் தனிப்பட்ட தரவைப் பெறாமல் integration, நிறுவனம், scopes மற்றும் விசை வரம்புகளைச் சரிபார்க்கவும்.
Scopes
| வரம்பு | அனுமதிப்பது |
|---|---|
contacts.read | தொடர்புகளைப் பட்டியலிட்டு மீட்டெடுக்க. நிறுவனக் கணக்கு மற்றும் அணுகல் கொண்ட உறுப்பினர் தொடர்புகள் இதில் சேர்க்கப்படாது. |
contacts.write | தொடர்பு upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
tasks.read | தனிப்பட்டவை அல்லாத பணிகளைப் பட்டியலிட்டு மீட்டெடுக்க. |
tasks.write | பணி upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
protocols.read | தனிப்பட்டவை அல்லாத நெறிமுறைகளைப் பட்டியலிட்டு மீட்டெடுக்க. |
protocols.write | நெறிமுறை upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
opportunities.read | வாய்ப்புகளைப் பட்டியலிட்டு மீட்டெடுக்க. |
opportunities.write | வாய்ப்பு upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
projects.read | திட்டங்களைப் பட்டியலிட்டு மீட்டெடுக்க. |
projects.write | திட்டம் மற்றும் பங்கேற்பாளர் upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
milestones.read | திட்ட மைல்கற்களைப் பட்டியலிட்டு மீட்டெடுக்க. |
milestones.write | மைல்கல் upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
members.read | உறுப்பினர் Customer ID, User ID மற்றும் காட்சிப் பெயர் மட்டும் கொண்ட ஏற்றுக்கொள்ளப்பட்ட உறுப்பினர்களைப் பட்டியலிட. |
events.read | நிகழ்வுகள் மற்றும் அடிப்படை அட்டவணைகளைப் பட்டியலிட்டு மீட்டெடுக்க. |
events.write | நிகழ்வு upsert செயல்பாடுகளைச் சரிபார்த்து பயன்படுத்த. |
mails.read | நிறுவனம் சார்ந்த அனுப்பப்பட்ட மற்றும் தோல்வியடைந்த வெளிச்செல்லும் அஞ்சல் வரலாற்றைப் படிக்க. |
mail-drafts.read | இந்த ஒருங்கிணைப்பின் தனித்த மின்னஞ்சல் ஒப்புதல் வரைவுகள் மற்றும் விநியோக நிலையைப் படிக்க. |
mail-drafts.write | மனித ஒப்புதலுக்காக மின்னஞ்சல் வரைவுகளைத் தயாரிக்க அல்லது திருத்த; ஒருபோதும் ஒப்புதல் அளிக்கவோ அனுப்பவோ கூடாது. |
tags.read | ஆதரிக்கப்படும் நிறுவன வகைகளுக்குத் தேர்ந்தெடுக்கக்கூடிய குறிச்சொற்களைக் கண்டறிய. |
தனிப்பட்ட பணிகளும் நெறிமுறைகளும் இந்த API மூலம் ஒருபோதும் திருப்பி அனுப்பப்படாது. ஒரு வரம்பு இல்லையெனில், அது வெற்று முடிவாகக் கருதப்படாது; அங்கீகாரப் பிழை திருப்பி அனுப்பப்படும்.
உறுப்பினர் அல்லாத CRM தொடர்பு, Scoutello உள்நுழைவுடன் இணைக்கப்பட்டிருந்தாலும், படிக்கப்பட்டு குறிப்பிடப்படலாம். பதிலில் நிறுவனத்தின் CRM புலங்கள் மட்டுமே இருக்கும்; User அடையாளம் அல்லது அணுகல் புலங்கள் ஒருபோதும் இருக்காது. ஒரு பங்கு, அனுமதிகள், அழைப்பு, ஏற்றுக்கொள்ளல் அல்லது நிறுவனக் கணக்கு நிலை கொண்ட தொடர்புகள் தொடர்ந்து மறைக்கப்பட்டிருக்கும். உள்நுழைவுடன் இணைக்கப்பட்ட தொடர்பைத் திருத்துவது தடைசெய்யப்பட்டுள்ளது (protected_contact); மாற்றமில்லாத CRM புலங்களாக இருந்தாலும் இதற்கு விதிவிலக்கு இல்லை. பணி/நெறிமுறையிலிருந்து ஏற்கனவே படிக்கக்கூடிய தொடர்பைக் குறிப்பிட, contacts.write மூலம் externalId, scoutelloId மற்றும் விருப்பமான externalUpdatedAt ஆகியவற்றை மட்டும் பயன்படுத்தி அதன் வெளிப்புற இணைப்பை அமைக்கலாம். பின்னர் இணைப்பு மெட்டாடேட்டாவை மட்டும் புதுப்பிக்க externalId மற்றும் விருப்பமான externalUpdatedAt ஆகியவற்றைப் பயன்படுத்தலாம்; இணைப்பு அமைந்த பிறகு தொடக்க scoutelloId-ஐத் தவிர்க்கவும். இதனால் தொடர்பிலோ அதன் User-இலோ எந்த மாற்றமும் ஏற்படாது. ஏற்றுக்கொள்ளப்பட்ட உறுப்பினர் ஒதுக்கீட்டுக்கு தனியான members.read projection பயன்படுத்தப்படுகிறது.
புதிய விசைகள் sctl_api_ முன்னொட்டைப் பயன்படுத்தி, contacts.write-இல் மட்டுமே தொடங்கும். மற்ற அனைத்து ஸ்கோப்புகளும் நிறுவன நிர்வாகி விசையை உருவாக்கும்போது அல்லது சுழற்றும்போது வழங்க வேண்டிய வெளிப்படையான விருப்பத் தேர்வுகளாகும். ஏற்கனவே உள்ள நற்சான்றுகள் அவற்றின் தற்போதைய ஸ்கோப்புகளைத் தக்கவைத்து, செல்லுபடியாகத் தொடரும்.
திட்டத்துடன் இணைக்கப்பட்ட தொடர்புகள் மற்றும் மின்னஞ்சல் வரைவுகள்
தொடர்பு upsert செயல்பாடுகள் விருப்பத்தேர்வு projectScoutelloId / projectExternalId மற்றும் companyScoutelloId / companyExternalId ஜோடிகளை ஏற்கும் (ஒவ்வொரு ஜோடியிலும் ஒன்றைத் தேர்ந்தெடுக்கவும்). ஒவ்வொரு உருப்படிக்கும் தொடர்பு, நிறுவனத் தொடர்பு மற்றும் திட்ட உறுப்பினர் நிலை அணுவகையாகச் சேமிக்கப்படும். திட்ட உறுப்பினர் நிலையைச் சேர்க்க projects.write தேவை; விடுபட்ட குறிப்புகள் பிற தொடர்புகளையும் உறுப்பினர் நிலைகளையும் அப்படியே வைத்திருக்கும். projects.read வழங்கப்பட்டால், தொடர்பு விவரங்களை மீண்டும் வாசிக்கும் போது projectParticipations அடங்கும். தொடர்புகளை மீண்டும் பயன்படுத்தினாலும், விற்பனைத் திட்ட ஏஜெண்டுகள் திட்டக் குறிப்பை வெளிப்படையாகச் சேர்க்க வேண்டும்.
தனித்தனி வரைவுகள், workflow run இன்றி, ஏற்கனவே உள்ள மனிதர் ஒப்புதல் முறையைப் பயன்படுத்தும்:
| முறை | பாதை | நோக்கம் |
|---|---|---|
| GET | /mail-drafts | ஒருங்கிணைப்புக்குச் சொந்தமான பக்கமிடப்பட்ட வரைவுகள்; விருப்பத்தேர்வு projectScoutelloId மற்றும் status வடிகட்டிகள். |
| GET | /mail-drafts/{scoutelloId} | தற்போதைய பதிப்பு, மதிப்பாய்வு இணைப்பு, உள்ளடக்க ஹாஷ், ஒப்புதல்/அனுப்பல் நிலை மற்றும் இறுதியில் கிடைக்கும் அஞ்சல் ID. |
| GET | /mail-drafts/external/{externalId} | நிலையான ஒருங்கிணைப்பு வெளிப்புற ID-ஐத் தேடுதல். |
| POST | /mail-drafts/batch-upsert | வரைவு தயாரிப்பைச் சரிபார்த்தல் அல்லது செயல்படுத்தல். |
வரைவு தயாரிப்புக்கு mail-drafts.write, contacts.read மற்றும் projects.write தேவை. குறிப்பிடப்பட்ட தொடர்பு திட்டப் பங்கேற்பாளராக மாறும். ஒப்புதல் வழங்குபவர், மின்னஞ்சல் திருத்த அனுமதியுள்ள ஏற்றுக்கொள்ளப்பட்ட நிறுவன உறுப்பினராக இருக்க வேண்டும். அனுப்புநர் தேர்வு, அந்த உறுப்பினருக்கான ஏற்கனவே அனுமதிக்கப்பட்ட நிறுவன அல்லது தனிப்பட்ட அனுப்புநர் அமைப்புகளைப் பயன்படுத்தும்; தன்னிச்சையான From முகவரிகள் ஏற்கப்படாது.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
mode: "apply" மூலம் மீண்டும் முயற்சிக்கும் முன் ஒவ்வொரு சரிபார்ப்பு முடிவையும் ஆய்வு செய்யவும். பெறப்பட்ட ID-ஐ வாசித்து reviewUrl, draftVersion, contentHash, status, dispatchStatus மற்றும் mailScoutelloId ஆகியவற்றைப் பெறவும். உருவாக்கத்திற்காக மட்டும் expectedVersion: 0-ஐப் பயன்படுத்தவும்; திருத்தங்களுக்கு தற்போது திரும்பப் பெறப்பட்ட பதிப்பைப் பயன்படுத்தவும். சூழலும் ஒப்புதல் வழங்குபவரும் மாற்றமுடியாதவை; மாற்றப்பட்ட உள்ளடக்கத்தைக் கொண்ட மதிப்பாய்வு செய்யப்பட்ட அல்லது அனுப்பப்பட்ட வரைவுகள் நிராகரிக்கப்படும். ஒரே மாதிரியான மீண்டும் முயற்சிகள் அசல் வரைவையே திருப்பி வழங்கும்.
வரைவுகள் திட்டம்/தொடர்பு Email தாவல்களிலும் டாஷ்போர்டு ஒப்புதல் அறிவிப்புகளிலும் தோன்றும். API தயாரிப்பு எந்த மின்னஞ்சலையும், அறிவிப்பு மின்னஞ்சல்களையும் உட்பட, அனுப்பாது; ஏற்கனவே உள்ள பணிச்சுற்று அறிவிப்பு-மின்னஞ்சல் நடத்தை மாற்றமின்றி இருக்கும். ஒதுக்கப்பட்ட மனிதர் பெறுநர்கள், பொருள், உள்ளடக்கம் மற்றும் ஆதரிக்கப்படும் இணைப்புகளைத் திருத்தி, பதிப்பைச் சேமித்து, பின்னர் ஒப்புதல் அளித்து அனுப்பு என்பதைத் தேர்ந்தெடுக்கலாம். ஒருங்கிணைப்புகளால் ஒப்புதல் அளிக்கவோ அனுப்பலைத் தொடங்கவோ முடியாது. தோல்வியுற்ற அல்லது தெளிவற்ற அனுப்பல் ஒருபோதும் கண்மூடித்தனமாக மீண்டும் முயற்சிக்கப்படாது. நெறிமுறை அடிப்படையிலான வரைவுகளை மாற்றும்போது, நெறிமுறைகளைப் பாதுகாத்து, அவற்றின் மாற்றுகளுக்கான குறுக்கு-குறிப்புகளைப் பராமரிக்கவும்.
MCP அணுகல்
அதே Scoutello API விசையையும் scope-களையும் streamable HTTP MCP endpoint உடன் பயன்படுத்தலாம்:
https://admin.scoutello.com/api/v1/mcp
MCP கிளையண்டை Authorization: Bearer YOUR_API_KEY அனுப்பும் வகையில் கட்டமைக்கவும். legacy /api/mcp URL, பாதை இணக்கத்தன்மை alias ஆகத் தொடர்கிறது; ஆனால் புதிய கிளையண்டுகள் versioned endpoint-ஐப் பயன்படுத்த வேண்டும். முன்னைய sctl_mcp_ நற்சான்றுகள் ஏற்கப்படாது; அவற்றுக்கு பதிலாக Scoutello API integration key-ஐப் பயன்படுத்தவும்.
MCP கருவிகள் REST ஒப்பந்தத்துடன் நேரடியாகப் பொருந்துகின்றன; அதே runtime schemas, tenant checks, integration lifecycle, rate limit மற்றும் service methods ஆகியவற்றைப் பயன்படுத்துகின்றன. எடுத்துக்காட்டாக, contacts_list, contacts_get, contacts_get_by_external_id மற்றும் contacts_batch_upsert ஆகியவை நான்கு தொடர்பு வழித்தடங்களையும் பிரதிபலிக்கின்றன. இதே முறை tasks, protocols, opportunities, projects, milestones மற்றும் events-க்கும் பொருந்தும்; mail-க்கு mails_list மற்றும் mails_get, members-க்கு members_list, tags-க்கு tags_list ஆகியவை உள்ளன.
செயலில் உள்ள விசையின் scope-கள் அனுமதிக்கும் கருவிகளை மட்டுமே server விளம்பரப்படுத்தும். contacts.read கொண்ட விசையால் contact read கருவிகளைக் கண்டறிய முடியும்; ஆனால் contacts_batch_upsert-ஐக் கண்டறிய முடியாது. contacts.write கொண்ட விசைக்கு batch-upsert கருவி கிடைக்கும்; ஆனால் read கருவிகள் கிடைக்காது. whoami எப்போதும் கிடைக்கும். Write கருவிகள் அவற்றுக்குச் சமமான REST செயல்பாடுகளைப் போலவே உடனடி விளைவுகளை ஏற்படுத்தும். ஆகவே, ஒரு batch-ஐப் பயன்படுத்தாமல் ஆய்வு செய்ய வேண்டியபோது mode: "validate"-ஐப் பயன்படுத்தவும்.
MCP server-to-server முறையிலும் இயங்குகிறது; cross-origin உலாவி அணுகலை இது செயல்படுத்தாது. அதன் JSON-RPC போக்குவரத்துக்கு தனிப்பட்ட URL தேவைப்படுகிறது. அங்கீகாரமும் தரவு நடத்தையும் பகிரப்பட்டாலும், தனிப்பட்ட REST resource URL-ஐ இதனுடன் பகிர முடியாது.
முழுமையான கிளையண்ட் கட்டமைப்பு, சரிபார்ப்பு, கருவி mapping மற்றும் சிக்கல் தீர்வு வழிமுறைகளுக்கு, MCP ஒருங்கிணைப்பு வழிகாட்டியை பார்க்கவும்.
பதிவுகளைப் படித்தல்
Contacts, tasks, protocols, opportunities, projects, milestones மற்றும் events ஆகியவை ஒரே read வழித்தடங்களைப் பயன்படுத்துகின்றன:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
பிற synchronization resources-க்கு contacts-ஐ tasks, protocols, opportunities, projects, milestones அல்லது events மூலம் மாற்றவும். இந்த integration மூலம் பதிவு இணைக்கப்பட்டிருந்தால், read DTO-வில் externalId தோன்றும்.
ஒரு பட்டியல் பதிலில் இந்த உறை இருக்கும்:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit 1 முதல் 100 வரை இருக்க வேண்டும். முடிவுகள், அவற்றின் பொது API பிரதிநிதித்துவம் மாற்றப்பட்ட பயனுள்ள நேரத்தின்படியும், பின்னர் Scoutello ID-யின்படியும் வரிசைப்படுத்தப்படும். ஒருங்கிணைப்பு-இணைப்பு மெட்டாடேட்டா மாறும்போது, இந்தப் பயனுள்ள நேரம் திருப்பி வழங்கப்பட்ட updatedAt-ஐ விட பின்னர் இருக்கலாம். கர்சர்கள் வெளிப்படையானவை அல்ல: அவற்றை மாற்றமின்றி சேமித்து அனுப்பவும்; அவற்றின் உள்ளடக்கத்திலிருந்து பொருளைப் புரிந்துகொள்ள முயலாதீர்கள்.
முதல் பதில், அந்தப் பயணத்திற்கான snapshotAt-ஐ நிர்ணயிக்கும். மற்றொரு incremental read-ஐத் தொடங்குவதற்கு முன், nextCursor-ஐப் பின்தொடர்ந்து, hasMore false ஆகும் வரை தொடரவும். பக்கமிடலின்போது பதிவுகள் மாறுவதால் தற்போதைய பயணம் நிலையற்றதாக மாறுவதை இது தடுக்கிறது.
Incremental synchronization-க்கு, ஒவ்வொரு கர்சர் பக்கத்தையும் பெற்று, அந்தப் பயணத்தின் snapshotAt-ஐ high-water timestamp ஆகச் சேமிக்கவும். அடுத்த பயணத்தில், அதை ISO 8601 updatedSince மதிப்பாக அனுப்பவும். கீழ் வரம்பு உள்ளடக்கியது; எனவே நிறைவடைந்த snapshot-ஐ மீண்டும் முயற்சிக்கும்போது எல்லை பதிவுகள் திரும்பக்கூடும், ஆனால் அவை தவறவிடப்படாது.
ஒற்றைப் பதிவு பதிலில் இந்த உறை இருக்கும்:
{
"data": {},
"requestId": "request-id"
}
ஒற்றை-தொடர்பு பதில்களில் relations வரிசையும் இடம்பெறும். ஒவ்வொரு தொடர்பும் அதன் Scoutello தொடர்பு ID, உருவாக்க நேரம், வகை, குறிப்புகள், connectedFrom மற்றும் connectedTo தொடர்பு குறிப்புகளைத் தக்கவைக்கும். தொடர்புக் குறிப்புகளில் Scoutello ID-யும், இருந்தால் இந்த ஒருங்கிணைப்பின் வெளிப்புற ID-யும் இடம்பெறும். API-யின் நிறுவன அணுகல் தனியுரிமை வரம்பிலிருந்து விலக்கப்பட்ட தொடர்புகள், தொடர்புகள் வழியாக வெளிப்படுத்தப்படாது. தொடர்புப் பட்டியல் பதில் சுருக்கமாகவே இருந்து, தொடர்புகளை உள்ளடக்காது; தொடர்பு விவரங்கள் தேவைப்பட்டால், ஒற்றை-தொடர்பு வழிகளில் ஏதேனும் ஒன்றைப் பயன்படுத்தவும்.
பணி வடிகட்டிகள் மற்றும் கர்சர் வரம்பு
தொடர்புப் பட்டியல்கள் search, type (person, company, supplier, other), status மற்றும் tagIds ஆகியவற்றை ஏற்கும். தேடல் உரை trim செய்யப்பட்டதும், எழுத்து வேறுபாடு கருதாததுமானதாகவும், 200 எழுத்துகள் / இடைவெளியால் பிரிக்கப்பட்ட 10 tokens-க்கு மட்டுப்படுத்தப்பட்டதாகவும் இருக்கும். ஒவ்வொரு token-மும் firstName, lastName அல்லது companyName ஆகியவற்றில் குறைந்தது ஒன்றில் இடம்பெற வேண்டும்; lastName-ல் சேமிக்கப்பட்ட legacy company names-உம் இதில் அடங்கும். % மற்றும் _ போன்ற எழுத்துகள் சொற்பொருளில் பொருத்தப்படும். Tags any-of பொருத்தத்தைப் பயன்படுத்தி, 1–50 IDs-ஐ ஏற்கும். வழங்கப்பட்ட அனைத்து வடிகட்டிகளும் AND நிபந்தனையுடன் இணைக்கப்படும். REST tag IDs-ஐ மீண்டும் வரும் parameters ஆக encode செய்கிறது; MCP அவற்றை array ஆக வழங்குகிறது:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
தொடர்பு கர்சர்கள் நிறுவனம், ஒருங்கிணைப்பு மற்றும் ஒவ்வொரு வடிகட்டியுடனும் இணைக்கப்பட்டிருக்கும். ஒவ்வொரு பக்கத்திலும் வடிகட்டிகளைத் தொடரவும்; வடிகட்டியை மாற்றினால் கர்சர் நிராகரிக்கப்படும். Tag வரிசை/நகல்கள் மற்றும் தேடல் token வரிசை/எழுத்து வடிவம்/whitespace ஆகியவை பயனுள்ள வடிகட்டியை மாற்றாது.
பணி பட்டியல் வழித்தடங்கள் பின்வரும் கூடுதல் வடிப்பான்களை ஏற்கின்றன; பிற வளம்/புல இணைப்புகள் நிராகரிக்கப்படுகின்றன:
| வளம் | வடிப்பான்கள் |
|---|---|
| பணிகள் | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| நெறிமுறைகள் | projectScoutelloId, milestoneScoutelloId, status (draft அல்லது final) |
| வாய்ப்புகள் | projectScoutelloId, stage, ownerScoutelloUserId |
| திட்டங்கள் | status, assignedContactScoutelloId |
| மைல்கற்கள் | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore என்பது பிரத்தியேகமானது; dueAfter உள்ளடக்கியது. இவை பணியின் நிறைவு தேதியையோ மைல்கல்லின் முடிவு தேதியையோ ஒப்பிடுகின்றன; அந்தத் தேதி இல்லாத பதிவுகள் பொருந்தாது. நேர மண்டலத்துடன் கூடிய ISO தேதி-நேரங்களை வழங்கவும். அனைத்து வடிப்பான்களும் பக்கமிடலுக்கு முன் பயன்படுத்தப்படும். கர்சரைத் தொடரும்போது, updatedSince உட்பட அதே வடிப்பான்களையும் அதே நிறுவன/ஒருங்கிணைப்பு இணைப்பையும் பயன்படுத்தவும். பக்க அளவை மாற்றலாம். இந்த வெளியீட்டிற்குப் பிறகு, பழைய வரம்பிடப்படாத கர்சர்கள் சேமிக்கப்பட்ட உயர்-நீர் நேரமுத்திரையிலிருந்து மீண்டும் தொடங்க வேண்டும்.
திட்டங்கள், மைல்கற்கள், ஒதுக்கீடுகள் மற்றும் குறிப்புகள்
GET /members (MCP members_list) நிலையான பக்கமிடலைப் பயன்படுத்துகிறது மற்றும் members.read தேவைப்படுகிறது. இது scoutelloId (உறுப்பினர் Customer ID), scoutelloUserId (User ID), மற்றும் displayName ஆகியவற்றை வழங்குகிறது. ஒரு பங்கு கொண்ட, ஏற்றுக்கொள்ளப்பட்ட நிறுவன உறுப்பினர்கள் மட்டுமே தோன்றுவர்; இந்தத் தேடல் மின்னஞ்சல் முகவரிகள் அல்லது அனுமதிகளை வெளிப்படுத்தாது.
பணிகள் assignedScoutelloUserIds-ஐ ஏற்கின்றன; வாய்ப்புகள் ownerScoutelloUserId-ஐப் பயன்படுத்துகின்றன. திட்டங்களும் மைல்கற்களும் assignedContacts: [{"scoutelloId":"member-customer-id"}]-ஐப் பயன்படுத்துகின்றன. ஒதுக்கீடுகளுக்கு நற்சான்றிதழின் நிறுவனத்தைச் சேர்ந்த ஏற்றுக்கொள்ளப்பட்ட உறுப்பினர்கள் தேவை. ஒதுக்கீடுகள் விடுபட்டால் அவை மாற்றமின்றி இருக்கும்; [] அவற்றை அழிக்கும். திட்டம், மைல்கல், பணி மற்றும் நெறிமுறை இறக்குமதிகள் அமைதியானவை: அவை ஒதுக்கீட்டு அறிவிப்புகளையோ தகவல்தொடர்புகளையோ அனுப்பாது.
நிகழ்வு assignedContacts, உறுப்பினர் Customer ID மூலம் வழங்கப்படும் வாசிக்கக்கூடிய CRM தொடர்புகளையும் ஏற்றுக்கொள்ளப்பட்ட உறுப்பினர்களையும் ஆதரிக்கிறது. ஏற்றுக்கொள்ளப்பட்ட உறுப்பினர்களை சாதாரண CRM தொடர்புக் குறிப்புகளாகவோ வெளிப்புற இணைப்பு இலக்குகளாகவோ பயன்படுத்த முடியாது; குழுப் பொறுப்புக்கு உறுப்பினர் ஒதுக்கீட்டுப் புலத்தைப் பயன்படுத்தவும்.
name மற்றும் projectScoutelloId அல்லது projectExternalId ஆகியவற்றில் ஒன்றைக் கொண்டு மைல்கற்களை உருவாக்கவும். இவை description (Markdown), status (open, in_progress, completed, closed), nullable startDate/endDate, order (இயல்புநிலை 0), மற்றும் assignedContacts ஆகியவற்றை ஆதரிக்கின்றன. தொடக்கத் தேதிக்கு முன் முடிவுத் தேதி இருக்கக்கூடாது. ஒவ்வொரு மைல்கல்லுக்கும் ஒருங்கிணைப்புக்குள் வரையறுக்கப்பட்ட நிலையான வெளிப்புற இணைப்பு உள்ளது. அதன் திட்டத்தை API மூலம் மாற்ற முடியாது. உருவாக்கும்போதும் புதுப்பிக்கும்போதும், பெயரும் விளக்கமும் நிறுவனத்தின் மொழியில் உள்ளூர்மயமாக்கப்படும்.
பணிகளும் நெறிமுறைகளும் திட்டம், மைல்கல் மற்றும் வாய்ப்பு குறிப்புகளை <entity>ScoutelloId அல்லது <entity>ExternalId ஆக ஏற்கின்றன; எடுத்துக்காட்டாக, milestoneExternalId. ஒவ்வொரு தொடர்பிற்கும், அழிக்கும்போதும் null பயன்படுத்தும்போது உட்பட, ஒரே ஒரு எழுத்து வடிவத்தை மட்டுமே வழங்கவும். எல்லா தொடர்புகளும் நற்சான்றிதழின் நிறுவனத்துக்குச் சேர்ந்தவையாக இருக்க வேண்டும். மைல்கல் மட்டும் கொண்ட குறிப்பு திட்டத்தைத் தானாகக் கண்டறியும்; முரண்படும் திட்டம் அல்லது அதன் மைல்கல்லைத் தக்கவைத்தபடி திட்டத்தை வெளிப்படையாக அழிப்பது நிராகரிக்கப்படும். திட்டத்துடன் இணைக்கப்பட்ட வாய்ப்பு, பணியின் திட்டத்துடன் பொருந்த வேண்டும். விடுபட்ட தொடர்புகள் தற்போதைய மதிப்புகளைத் தக்கவைக்கும்; வெளிப்படையான null, மீதமுள்ள சூழல் செல்லுபடியாக இருந்தால், ஒரு தொடர்பை அழிக்கும். வாசிப்பு முடிவுகளில் இரு ID எழுத்து வடிவங்களும் பணிப் பொறுப்பளிப்புகளும் வெளிப்படுத்தப்படும்.
பணி திட்டமிடலும் பணிச்செயல்வழிகளும்
Task status என்பது பணியின் செயல்திறன் வாய்ந்த பணிச்செயல்வழியில் உள்ள ஒரு நிலையின் மாற்ற முடியாத திறவுகோல்; இது நிலையான enum அல்ல. tasks.read scope-ஐப் பயன்படுத்தி GET /task-workflows மூலம் கிடைக்கும் நிறுவன மற்றும் திட்டப் பணிச்செயல்வழிகளைப் படிக்கவும். ஒவ்வொரு நிலையும் அதன் திறவுகோல், லேபிள், lifecycle type (backlog, unstarted, started, completed அல்லது cancelled), நிறம், வரிசை, இயல்புநிலை கொடி மற்றும் காப்பக நிலை ஆகியவற்றைக் கொண்டிருக்கும். நிறுவனப் பணிச்செயல்வழி பெறப்பட்டதா என்பதைத் திட்டப் பதிவுகள் குறிப்பிடும். பணிச்செயல்வழி உள்ளமைவு dashboard நிர்வாகத்திலேயே இருக்கும்.
பணிகள் nullable priority (low, medium, high அல்லது urgent) மற்றும் estimatedEffortMinutes ஆகியவற்றையும், nullable startDate மற்றும் dueDate ஆகியவற்றையும் ஏற்கின்றன. பணி வாசிப்பு முடிவுகளில் denormalized statusType, parent குறிப்பு, சுருக்கமான துணைப் பணி குறிப்புகள் மற்றும் blockedBy / blocks குறிப்புகள் அடங்கும்.
parentTaskScoutelloId அல்லது parentTaskExternalId மூலம் ஒரு நிலை துணைப் பணியை உருவாக்கவும் அல்லது புதுப்பிக்கவும்; null அதை மேல்நிலைப் பணியாக மாற்றும். சார்புகள், blockedBy மற்றும் blocks ஆகியவற்றில் { "scoutelloId": "..." } அல்லது { "externalId": "..." } குறிப்புகளைக் கொண்ட வரிசைகளைப் பயன்படுத்துகின்றன. தொடர்பு புலங்கள் விடுபட்டால் அவை அப்படியே பாதுகாக்கப்படும்; காலியான சார்பு வரிசை அந்தத் திசையில் உள்ள சார்புகளை அழிக்கும். உள்ளமைக்கப்பட்ட துணைப் பணிகள், பெற்றோர்-குழந்தை சார்புகள், நிறுவனங்களுக்கு இடையிலான சார்புகள், நகல்கள், சுயக் குறிப்புகள் மற்றும் நேரடி அல்லது இடைமாறுச் சுழற்சிகளை API நிராகரிக்கும்.
பணிப் பட்டியல் வடிகட்டிகள் துல்லியமான workflow status, lifecycle statusType, priority, parentState (top_level, subtask அல்லது parent), மற்றும் blockedState (blocked, blocking அல்லது unblocked) ஆகியவற்றை ஏற்கின்றன.
நெறிமுறைகள் கூடுதலாக status: "draft" | "final"-ஐ ஏற்கின்றன (புதிய பதிவுகள் இயல்பாக final ஆக இருக்கும்). புதிய நெறிமுறைக்கு type, date மற்றும் ஒரு தொடர்பு அல்லது செல்லுபடியாகும் திட்டம்/மைல்கல் சூழல் தேவை. contactExternalId: null, திட்டம்/மைல்கல் சூழல் தொடர்ந்தால் மட்டுமே அதன் தொடர்பை அழிக்கும். எனவே, வாடிக்கையாளரை உருவாக்கிக் காட்டாமல் உள்துறை திட்டக் குறிப்புகளை உருவாக்கவும் படிக்கவும் முடியும். Draft/final குறிப்பின் நிலையை விவரிக்கும்; எந்தத் தகவல்தொடர்பும் அனுப்பப்படாது. தனிப்பட்ட பணிகளும் நெறிமுறைகளும் தொடர்ந்து அணுக முடியாதவையாக இருக்கும்.
திட்டப் பங்கேற்பாளர்கள்
திட்ட participants-ல், contact குறிப்பைப் பயன்படுத்தி அடுக்குச் சேர்க்கை புதுப்பிப்புகள் உள்ளன. உதாரணம்:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
பங்கேற்பாளர்கள் ஒரு திட்டத்துடன் தொடர்புடைய சாத்திய வாடிக்கையாளர்கள்/வாடிக்கையாளர்களைக் குறிக்கின்றனர்; பொறுப்புக்கூற வேண்டிய உறுப்பினர்களுக்கு assignments பயன்படுத்தப்படுகின்றன. பங்கேற்பாளர்கள் விடுபட்டது, காலியான வரிசை மற்றும் விடுபட்ட பங்கேற்பாளர் புலங்கள் ஏற்கனவே உள்ள தரவைப் பாதுகாக்கும். null, role, notes அல்லது groupScoutelloId-ஐ அழிக்கும். ஒரே payload-இல் ஒரே தீர்மானிக்கப்பட்ட தொடர்புகள் மீண்டும் இடம்பெற்றால் நிராகரிக்கப்படும். குழுக்கள் ஏற்கனவே தேர்ந்தெடுக்கப்பட்ட திட்டத்தைச் சேர்ந்தவையாக இருக்க வேண்டும்; வாசிப்புகளில் participantGroups (ID/பெயர்), பங்கேற்பாளர் ID-கள், தொடர்புகள், பங்கு, குறிப்புகள் மற்றும் குழு ID ஆகியவை அடங்கும். பங்கேற்பாளர்களை அகற்றுவதும் குழுக்களை உருவாக்குவதும் தற்போது dashboard-இல் கிடைக்கின்றன.
பதிவுகளைத் தொகுப்பாகச் சேர்த்து புதுப்பித்தல்
வளத்தின் batch route மூலம் அதிகபட்சம் 100 பதிவுகளை எழுதவும்:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
பணி தொகுப்புகள், பெற்றோர் மற்றும் சார்பு உறவுகளைப் பயன்படுத்துவதற்கு முன் அவற்றின் பணி பதிவுகளைத் தீர்மானிக்கும். இந்த இரு-கட்ட செயலாக்கம், ஒரே தொகுப்பில் உருவாக்கப்பட்ட மற்றொரு பணியை, அது எந்த வரிசையில் இருந்தாலும், அதன் வெளிப்புற ID மூலம் பெற்றோர், blocker அல்லது blocked task ஆகக் குறிப்பிட அனுமதிக்கிறது.
ஒவ்வொரு வளத்தின் புலங்கள் மற்றும் சரிபார்ப்பு கட்டுப்பாடுகளுக்கு OpenAPI ஆவணத்தைப் பயன்படுத்தவும். ஒவ்வொரு பதிவிலும் 1 முதல் 200 எழுத்துகளுக்குள் நிலையான externalId இருக்க வேண்டும். அதை மாற்றமற்ற தொழில்நுட்ப அடையாளமாகக் கருதவும்: மின்னஞ்சல் முகவரி, பெயர், API ரகசியம் அல்லது பிற தனிப்பட்ட தரவைப் பயன்படுத்த வேண்டாம். externalUpdatedAt விருப்பத்தேர்வாகும்; இருப்பினும், மூல அமைப்பு நம்பகமான மாற்ற நேரமுத்திரையை வழங்கும்போது அதை வழங்குவது வலுவாகப் பரிந்துரைக்கப்படுகிறது.
கோரிக்கை உடல் 1 MiB-க்கு வரையறுக்கப்பட்டுள்ளது. mode இயல்பாக apply ஆக இருக்கும்:
applyஏற்கப்பட்ட பதிவுகளைச் சரிபார்த்து எழுதுகிறது.validateஎழுதாமல் அதே சரிபார்ப்பு மற்றும் பொருத்துதலைச் செய்து,would_*முடிவுகளை வழங்குகிறது.
தொடர்பு இறக்குமதிகளுக்கு, கோரிக்கையில் matchByEmail என்பதை true ஆக அமைக்கலாம். இது இயல்பாக false ஆக இருக்கும்; வெளிப்புற ID என்பது மிகவும் பாதுகாப்பான இயல்புநிலை அடையாள எல்லையாகும்.
விடுபட்ட புலங்கள் தற்போதைய மதிப்பைத் தக்கவைக்கின்றன. வெளிப்படையாக வழங்கப்படும் null, null மதிப்பை ஏற்கும் புலத்தை அழிக்கிறது; வழங்கப்படும் காலியான assignment/tag வரிசை அந்தத் தொடர்பை அழிக்கிறது. Project participants சேர்க்கை upsert-களாகும்: காலியான வரிசை பட்டியலை மாற்றாது. தொடர்புகள், பணிகள், வாய்ப்புகள் மற்றும் நிகழ்வுகளுக்கான tag எழுத்துகள் Scoutello tag ID-களைப் பயன்படுத்துகின்றன. தொடர்பு வெளிப்புற ID-கள் தற்போதைய ஒருங்கிணைப்புக்குச் சொந்தமான இணைப்புகள் மூலமே தீர்மானிக்கப்படுகின்றன; உரிமை அல்லது பொறுப்புக்குப் பயன்படுத்தப்படும் Scoutello user ID-கள் தற்போதைய நிறுவனத்தின் ஏற்கப்பட்ட உறுப்பினர்களைக் குறிக்க வேண்டும்.
வாய்ப்பு உருவாக்கங்களுக்கு account அல்லது contact அவசியம்; இழந்த வாய்ப்புகளுக்கு இழப்புக் காரணம் அவசியம். பணத் தொகைகள் integer cents-ஆகப் பயன்படுத்தப்படுகின்றன. Project மற்றும் event பெயர்கள் மற்றும் விளக்கங்கள் நிறுவனத்தில் அமைக்கப்பட்ட மொழியில் வாசிக்கப்பட்டும் எழுதப்பட்டும் இருக்கும். நிகழ்வு எழுத்துகள் வெளிப்படையான தேதிகளையும், விலக்குகளுடன் கூடிய தினசரி, வாராந்திர அல்லது மாதாந்திர மீள்நிகழ்வையும் ஆதரிக்கின்றன; வெளியிடப்பட்ட visibility tier-கள் Scoutello-வின் சட்டத் தயார்நிலைத் தடைகளுக்கு உட்பட்டவையாகவே இருக்கும். நிகழ்வு ticketing, பங்கேற்பாளர்கள், media, templates, newsletters, collaborations அல்லது பிற மேம்பட்ட நிகழ்வு மேலாண்மைக் கட்டுப்பாடுகளை API வெளிப்படுத்தாது.
Tags-ஐக் கண்டறிதல்
tagIds-ஐ வழங்குவதற்கு முன் tags endpoint-ஐப் பயன்படுத்தவும்:
GET /tags?entity=events&type=category
entity அவசியமானது; இது contacts, tasks, opportunities அல்லது events ஆகியவற்றை ஏற்கிறது. இது தொடர்புடைய சேமிக்கப்பட்ட tag relevancy-க்கு map செய்யப்படுகிறது. type விருப்பத்தேர்வாகும்; இது category அல்லது attribute ஆகியவற்றை ஏற்கிறது. தேர்ந்தெடுக்கக்கூடிய categories நிறுவனம் சார்ந்தவையாகவோ global-ஆகவோ இருக்கலாம்; தேர்ந்தெடுக்கக்கூடிய attributes Scoutello-வின் curated global attribute தொகுப்பிலிருந்து பெறப்படுகின்றன. முடிவுகளில் scoutelloId, நிறுவன மொழியில் உள்ளூர்மயமாக்கப்பட்ட பெயர், type மற்றும் relevancy ஆகியவை அடங்கும். நிறுவனங்களுக்கு இடையேயான, தவறான relevancy-யுடைய மற்றும் தேர்ந்தெடுக்க முடியாத tag ID-கள், பாதிக்கப்பட்ட batch உருப்படியை நிராகரிக்கும்.
வெளியேறும் அஞ்சல் வரலாற்றைப் படித்தல்
அஞ்சல் வரலாறு படிக்க மட்டுமே:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
sent அல்லது failed நிலையில் உள்ள நிறுவனத்திற்குச் சொந்தமான அஞ்சல் மட்டுமே திருப்பி வழங்கப்படும். பதில்களில் பொதுவாகச் சேமிக்கப்பட்ட தலைப்புகள் மற்றும் உள்ளடக்கம், BCC, நிலை மற்றும் நேர முத்திரைகள், திட்டம்/நிகழ்வு/செய்திமடல் குறிப்புகள், இணைப்பு ID-கள் மற்றும் வகைகள், மேலும் மொத்தப் பெறுநர் விநியோகம்/திறப்பு/கிளிக்/திரும்பல்/புகார்/நிராகரிப்பு புள்ளிவிவரங்கள் அடங்கும். வரைவுகள், வரிசைப்படுத்தப்பட்ட அல்லது திட்டமிடப்பட்ட அஞ்சல், ஒவ்வொரு பெறுநருக்குமான வரிசைகள், வழங்கப்பட்ட முன்னோட்டங்கள், வழங்குநரின் மூலப் பிழைகள் மற்றும் இணைப்பு பதிவிறக்க URL-கள் ஒருபோதும் வெளிப்படுத்தப்படாது. பின்னர் பெறுநர் விநியோகப் புதுப்பிப்பு ஏற்பட்டால், அஞ்சலின் பயனுள்ள ஒத்திசைவு நேர முத்திரை முன்னேற்றப்படும்; இதனால் அதிகரிப்பு அடிப்படையிலான வாசிப்புகளில் அஞ்சல் மீண்டும் தோன்றும். அஞ்சலை எழுதுவதற்கான வழித்தடங்கள் எதுவும் இல்லை.
பயன்பாட்டு முடிவு created, updated, linked, unchanged, stale_ignored அல்லது rejected ஆக இருக்கலாம். சரிபார்ப்பிற்கு would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale அல்லது rejected பயன்படுத்தப்படும். தனிப்பட்ட பதிவுகள் நிராகரிக்கப்பட்டாலும், சரியான தொகுதி கோரிக்கை HTTP 200-ஐத் திருப்பி வழங்கும்; எனவே ஒவ்வொரு உருப்படியையும், பதில் சுருக்கத்தையும் எப்போதும் ஆய்வு செய்யவும். தோல்வியை விசாரிக்க Scoutello ஆதரவுக் குழுவைத் தொடர்புகொள்ளும்போது, பதிலில் requestId-ஐ வைத்திருக்கவும்.
நேர முத்திரைகள் மற்றும் முரண்பாடுகள்
externalUpdatedAt இருக்கும் போது, தொகுதியின் மீதமுள்ள பகுதிகள் தோல்வியடையாமல், காலாவதியான மாற்றங்களை நிராகரிக்க Scoutello அதைப் பயன்படுத்தும். stale_ignored முடிவு அந்தப் பழைய தரவுத் தொகுப்பிற்கு இறுதியானது; புதிய பதிப்பை அனுப்ப வேண்டுமா என்பதைத் தீர்மானிப்பதற்கு முன், தற்போதைய பதிவைப் பெறவும்.
நேர முத்திரைகளை UTC ISO 8601 மதிப்புகளாகக் கருதவும். அவற்றின் அசல் துல்லியத்தைப் பாதுகாக்கவும்; மூலப் பதிவின் மாற்ற நேரத்திற்குப் பதிலாக, ஒத்திசைவு வேலை நடந்த நேரத்தைப் பயன்படுத்த வேண்டாம்.
ஒரேமுறைச் செயலாக்கம்
ஒரேமுறைச் செயலாக்க வரம்பு ஒருங்கிணைப்பு மற்றும் externalId ஆகும். Scoutello ஒரு நிலையான payload hash-ஐயும் விருப்பமான externalUpdatedAt மதிப்பையும் ஒப்பிடுகிறது; எனவே அதே பதிவை மீண்டும் முயற்சிப்பது நகல்களை உருவாக்காது, மேலும் unchanged-ஐத் திருப்பி வழங்கலாம்.
externalUpdatedAt உடன், அதே நேர முத்திரையும் payload-உம் unchanged ஆகும்; பழைய நேர முத்திரை stale_ignored ஆகும்; அதே நேர முத்திரையுடன் வேறுபட்ட payload இருப்பது பதிப்பு முரண்பாடாகும். இதுவரை எந்த நேர முத்திரையையும் ஏற்காத இணைப்பிற்கு, அதே நேர முத்திரையற்ற payload unchanged ஆகவே இருக்கும்; மாற்றப்பட்ட payload வருகை வரிசைப்படி பயன்படுத்தப்படும். இணைப்பு ஒரு நேர முத்திரையை ஏற்றுக்கொண்ட பிறகு, externalUpdatedAt இல்லாத மாற்றப்பட்ட payload பதிப்பு முரண்பாடாக நிராகரிக்கப்படும்; இதனால் பதிப்பு கொண்ட நிலையை பதிப்பு அற்ற தரவு மேலெழுத முடியாது. இதனால்தான் மூல மாற்ற நேர முத்திரைகளைப் பயன்படுத்துவது வலுவாகப் பரிந்துரைக்கப்படுகிறது.
தணிக்கைப் பதிவு
Scoutello changelogs में स्वीकार की गई API create, update और केवल-लिंक सिंक्रनाइज़ेशन कार्रवाइयाँ स्रोत के रूप में Public API के साथ दिखाई देती हैं और संबंधित इंटीग्रेशन से जुड़ी होती हैं। परिचालन रन सारांश समस्या-निवारण के लिए अनुरोध आईडी और समेकित परिणाम-गणना सुरक्षित रखते हैं; वे रिकॉर्ड पेलोड या API सीक्रेट सुरक्षित नहीं रखते।
त्रुटियाँ और पुनःप्रयास
अनुरोध-स्तर की त्रुटियाँ इस एनवेलप का उपयोग करती हैं:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
HTTP 429 और अस्थायी 5xx प्रतिक्रियाओं पर एक्सपोनेंशियल बैकऑफ़ और जिटर के साथ पुनःप्रयास करें। Retry-After मौजूद होने पर उसका पालन करें। नेटवर्क विफलता Scoutello द्वारा अनुरोध स्वीकार किए जाने के बाद हुई हो सकती है; उसी बैच को दोबारा भेजना सुरक्षित है, क्योंकि प्रत्येक रिकॉर्ड बाहरी आईडी और कैनोनिकल पेलोड के आधार पर इडेम्पोटेंट होता है। अनुरोध बदले बिना प्रमाणीकरण, प्राधिकरण, सत्यापन, संस्करण-संघर्ष या व्यक्तिगत rejected परिणामों पर स्वचालित रूप से पुनःप्रयास न करें।
अनुशंसित दो-तरफ़ा सिंक लूप
- सेटअप के दौरान
/whoamiको कॉल करें और अपेक्षित संगठन तथा स्कोप सत्यापित करें। - पिछले पूर्ण किए गए हाई-वॉटर मार्क के बाद बदले गए प्रत्येक पृष्ठ को पढ़ें और उन बदलावों को बाहरी सिस्टम पर इडेम्पोटेंट तरीके से लागू करें।
- स्थिर बाहरी आईडी और स्रोत-संशोधन टाइमस्टैम्प का उपयोग करते हुए, बाहरी बदलाव
/batch-upsertको भेजें। - सभी पृष्ठों और आइटम परिणामों को संभालने के बाद ही चेकपॉइंट सुरक्षित करें।
- स्रोत सिस्टम के स्वामित्व नियमों के अनुसार संघर्षों का समाधान करें; खाली रिकॉर्ड भेजकर हटाने का अनुकरण न करें।
Scoutello इस पहले संस्करण में जानबूझकर कोई सार्वजनिक डिलीट रूट उपलब्ध नहीं कराता। जब तक दस्तावेज़ीकृत लाइफ़साइकल ऑपरेशन उपलब्ध न हो, तब तक हटाने या आर्काइव करने की नीतियों को API के बाहर संभालें।
मानवीय समीक्षा के लिए सोशल पोस्ट
सोशल API किसी नामित मानवीय समीक्षक के लिए पोस्ट तैयार करती है। यह उन्हें स्वीकृत या प्रकाशित नहीं कर सकती। REST और MCP समान स्कोप और सेवा का उपयोग करते हैं।
| स्कोप | /api/v1 के अंतर्गत एंडपॉइंट |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
नए स्कोप स्पष्ट रूप से प्रदान किए जाने चाहिए। मौजूदा क्रेडेंशियल को कोई अतिरिक्त
एक्सेस नहीं मिलता। सदस्य उपयोगकर्ता आईडी खोजने के लिए members.read का उपयोग करें और पोस्ट करने की अनुमति वाले समीक्षक (newsletter.edit) का चयन करें। ड्राफ़्ट के लिए CRM संपर्क या प्रोजेक्ट आवश्यक नहीं है।
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
publishMode: "now" மற்றும் scheduledAt: null ஆகியவற்றைப் பயன்படுத்தி, ஒப்புதல் கிடைத்ததும் வெளியிடவும். ஒவ்வொரு
சேனல் மாறுபாட்டிலும் அதன் முழு உரை, அமைப்புகள் மற்றும் வரிசைப்படுத்தப்பட்ட மீடியா ID-கள் இடம்பெறும்.
சேனல் கண்டறிதல், ஆதரிக்கப்படும் வடிவங்கள், வரம்புகள் மற்றும் அமைப்புகளை வழங்குகிறது. தற்போது
ஆதரிக்கப்படும் சேனல்கள் LinkedIn சுயவிவரங்கள்/பக்கங்கள், Facebook, Instagram மற்றும் Threads ஆகும்.
Instagram-க்கு மீடியா தேவை. ஒரு மாறுபாட்டில் அதிகபட்சம் பத்து படங்கள் அல்லது வீடியோக்களை ஏற்கலாம்.
தொகுப்புகளில், ஏற்கனவே உள்ள 1 MiB கோரிக்கை வரம்புக்குள் அதிகபட்சம் 100 தனித்துவமான வெளிப்புற ID-களை ஏற்கலாம்.
mode: "validate" குறிப்புகளை மற்றும் பதிப்புகளைச் சேமிக்காமல், வரைவுகளைச் சேமிக்காமல்,
சொத்துகளைப் பதிவேற்றாமல், அறிவிப்புகளை உருவாக்காமல் அல்லது பணியை வரிசைப்படுத்தாமல் சரிபார்க்கிறது. Apply முடிவுகளில்
ID-கள், மதிப்பாய்வு இணைப்புகள், பதிப்புகள் மற்றும் ஒவ்வொரு பதிவுக்கான முடிவுகள் இடம்பெறும். பகுதி தோல்விகள் வெற்றிகரமாகச்
செயல்பட்ட தொடர்புடைய பதிவுகளைத் திரும்பப்பெறாது. அறிவிப்பு தோல்வியுற்றால், சேமிக்கப்பட்ட
மதிப்பாய்வு URL-உடன் எச்சரிக்கை திருப்பி அனுப்பப்படும்.
திருத்துவதற்கு முன், தற்போதைய draftVersion-ஐப் பெறவும். ஒரே மாதிரியான
மீண்டும் முயற்சிகள் idempotent ஆக இருந்து, பின்னர் மனிதர்களால் செய்யப்பட்ட திருத்தங்களைப் பாதுகாக்கும். மதிப்பாய்வாளர்களை இடத்திலேயே மாற்ற முடியாது. ஒப்புதல் அல்லது நிராகரிப்புக்குப் பிறகு, மற்றொரு முன்மொழிவுக்கு புதிய வெளிப்புற ID-ஐப் பயன்படுத்தவும்.
வரைவு வாசிப்புகள் அழைப்பைச் செய்யும் ஒருங்கிணைப்புக்கு மட்டுமே வரையறுக்கப்பட்டவை; வெளியீட்டு வரலாறு
dashboard, script மற்றும் பழைய Scoutello இடுகைகள் உட்பட, நிறுவனத்தில் சேமிக்கப்பட்ட அனைத்து
Scoutello உருவாக்கிய பிரச்சாரங்களையும் உள்ளடக்கும். வெளிப்புற சேனல் வரலாறு இறக்குமதி செய்யப்படாது.
பட்டியல்கள் நிலையான limit, cursor மற்றும் updatedSince அளவுருக்களைப் பயன்படுத்தும். இடுகைகள் மற்றும்
வரைவுகள் channelId, status, after, before மற்றும் search ஆகியவற்றையும் ஏற்கும்; அடுத்தடுத்த cursor பக்கங்களில்
அனைத்து வடிப்பான்களையும் தொடர்ந்து வைத்திருக்கவும். தேதி வடிப்பான்கள் வெளியீட்டு நேரத்திற்குப் பொருந்தும்
(உடனடியாக நிலுவையில் உள்ள வரைவுகளுக்கு உருவாக்கப்பட்ட நேரம்). வரைவு status வடிப்பான்கள் ஒப்புதல்
நிலையை வடிகட்டும்; இடுகை status ஒரு பிரச்சார அல்லது சேனல் விநியோக நிலையைப் பொருத்தும். வாசிப்புகள்
கடைசியாக அறியப்பட்ட விநியோக நிலை, ஒவ்வொரு சேனலின் தோல்விகள், பொது இணைப்புகள் மற்றும் ஒத்திசைவு
நேரமுத்திரைகளை வெளிப்படுத்தும். வரைவு incremental வாசிப்புகள் பிரச்சார விநியோக மாற்றங்களையும் பிரதிபலிக்கும்.
மீடியாவைப் பதிவேற்றுதல்
POST /social-media/uploads-ஐclientUploadId,filename,contentType,sizeஆகியவற்றை பைட்டுகளாகவும், அசல் பைட்டுகளின் சிறிய எழுத்து ஹெக்சாடெசிமல்sha256-ஐயும் கொண்டு அழைக்கவும். ஆதரிக்கப்படும் வகைகள் PNG, JPEG, WebP, MP4, WebM, QuickTime மற்றும் M4V. பதிவேற்ற வரம்பு 500 MiB.- திரும்பப் பெறப்பட்ட
upload.url-க்கு அதன் தலைப்புகளைப் பயன்படுத்தி, அசல் பைட்டுகளை HTTPPUTமுறையில் அனுப்பவும். பதிவேற்ற URL-கள் 15 நிமிடங்களுக்குப் பிறகு காலாவதியாகும். அதே கோப்பிற்கான மீண்டும் முயற்சிகளில்clientUploadId-ஐப் பயன்படுத்தவும்; காலாவதியான அமர்வுகள் அல்லது வேறு கோப்புகளுக்கு புதிய ID தேவை. {}என்ற JSON உடலுடன்POST /social-media/uploads/{assetId}/finalize-ஐ அழைக்கவும். இறுதிப்படுத்தல் அளவு, வகை, கையொப்பம் மற்றும் செக்சம் ஆகியவற்றைச் சரிபார்த்து, தனிப்பட்ட நகலை உறையச்செய்து,mediaIds-க்கான சொத்து ID-ஐத் திருப்பி அளிக்கும். இறுதிப்படுத்தலை மீண்டும் செய்வது பாதுகாப்பானது.
பதிவேற்ற உரிமை நிறுவனம் மற்றும் ஒருங்கிணைப்புடன் இணைக்கப்பட்டுள்ளது. வரைவுகள் தங்கள் நிறுவனத்திலுள்ள இறுதிப்படுத்தப்பட்ட சொத்துகளை மேற்கோள் காட்டலாம். முன்னோட்ட URL-கள் தற்காலிகமானவை; அவற்றைப் புதுப்பிக்க வரைவை மீண்டும் பெறவும். இறுதிப்படுத்தப்பட்ட பொருட்களுக்கு பதிவேற்ற URL-கள் ஒருபோதும் வழங்கப்படாது.
மனித மதிப்பாய்வு மற்றும் விநியோகம்
மதிப்பாய்வாளருக்கு டாஷ்போர்டு அறிவிப்பு கிடைக்கும்; Postings-இலிருந்து அல்லது அதன் மதிப்பாய்வு URL மூலம் இடுகையைத் திறக்கலாம். திருத்தம் மற்றொரு மாற்ற முடியாத பதிப்பை உருவாக்கும். ஒப்புதல், காட்டப்படும் பதிப்பு மற்றும் உள்ளடக்க ஹாஷைப் பயன்படுத்தி, உறுப்பினர் நிலை, சேனல்கள் மற்றும் சொத்துகளை மீண்டும் சரிபார்த்து, அணுவியல் முறையில் ஒரு நிலையான பிரச்சாரத்தை உருவாக்கும். முன்மொழியப்பட்ட நேரம் கடந்துவிட்டால், மதிப்பாய்வாளர் வெளிப்படையாக புதிய நேரத்தைச் சேமிக்க வேண்டும் அல்லது ஒப்புதல் அளிக்கும் போது வெளியிடுவதைத் தேர்ந்தெடுக்க வேண்டும்.
வரிசை மீண்டும் முயற்சிகள் பிரச்சாரம் மற்றும் அதன் தள ரசீதுகளை மீண்டும் பயன்படுத்தும். ஒப்புதல் பெற்ற பிரச்சாரங்களை நடப்பிலேயே திருத்த முடியாது. டாஷ்போர்டு மூலம் ரத்து செய்தாலும் அவற்றின் ஒப்புதல் வரலாறும் ஊடகங்களும் பாதுகாக்கப்படும்; செயலில் உள்ள அனுப்பலை ரத்து செய்வதால் அது இடைநிறுத்தப்படாது. ஒப்புதல் மற்றும் உண்மையான தள விநியோகத்தை வேறுபடுத்த, வரைவு அல்லது பிரச்சாரத்தை வினவவும்.